react-native-roster 0.0.0 → 0.0.1

package/src/components/schedule/days/parts/grid.tsx

@@ -0,0 +1,21 @@
+import { View } from 'react-native';
+import type { ScheduleHoursInput } from '../../schedule.types';
+
+export function ScheduleGrid({ hours, pxPerHour }: ScheduleHoursInput) {
+  return (
+    <View pointerEvents="none" style={{ position: 'absolute', width: '100%' }}>
+      {hours.map((hour) => (
+        <View
+          key={hour}
+          testID="schedule-hour-band"
+          style={{
+            height: pxPerHour,
+            borderTopWidth: 1,
+            borderRightWidth: 1,
+            borderColor: '#e2e8f0',
+          }}
+        />
+      ))}
+    </View>
+  );
+}

package/src/components/schedule/days/parts/now-line.tsx

@@ -0,0 +1,11 @@
+import { View } from 'react-native';
+
+export function ScheduleNowLine({ y, column }: { y: number; column: number }) {
+  return (
+    <View
+      testID={`schedule-now-${column}`}
+      pointerEvents="none"
+      style={{ position: 'absolute', top: y, width: '100%', height: 2, backgroundColor: '#dc2626' }}
+    />
+  );
+}

package/src/components/schedule/days/parts/skipped-date.tsx

@@ -0,0 +1,22 @@
+import { Text, View } from 'react-native';
+
+export function ScheduleSkippedDate({ localDate }: { localDate: string }) {
+  return (
+    <View testID={`schedule-missing-${localDate}`} style={{ width: 0, zIndex: 1 }}>
+      <Text
+        accessibilityLabel={`Skipped local date ${localDate}`}
+        style={{
+          width: 110,
+          marginLeft: -55,
+          marginTop: 62,
+          fontSize: 9,
+          color: '#92400e',
+          backgroundColor: '#fef3c7',
+          textAlign: 'center',
+        }}
+      >
+        Skipped {localDate}
+      </Text>
+    </View>
+  );
+}

package/src/components/schedule/days/parts/transition.tsx

@@ -0,0 +1,70 @@
+import { Text, View } from 'react-native';
+import type { ScheduleTransitionInput } from '../../schedule.types';
+
+export function ScheduleTransition({
+  transition,
+  y,
+  dividerY,
+  height,
+  width,
+}: ScheduleTransitionInput) {
+  if (height === 0) return null;
+  if (transition.deltaMinutes < 0)
+    return (
+      <View
+        testID="schedule-repeat"
+        pointerEvents="none"
+        style={{
+          position: 'absolute',
+          top: dividerY,
+          width,
+          borderTopWidth: 1,
+          borderTopColor: '#92400e',
+        }}
+      >
+        <Text
+          style={{
+            fontSize: 9,
+            color: '#92400e',
+            backgroundColor: '#fffbeb',
+            alignSelf: 'flex-start',
+          }}
+        >
+          again
+        </Text>
+      </View>
+    );
+  return (
+    <View
+      testID="schedule-skip"
+      pointerEvents="none"
+      accessibilityLabel="Skipped time"
+      style={{
+        position: 'absolute',
+        top: y,
+        height,
+        width,
+        overflow: 'hidden',
+        backgroundColor: '#fef3c7',
+      }}
+    >
+      {Array.from({ length: Math.ceil((width + height) / 8) }, (_, index) => {
+        const left = index * 8 - height;
+        return (
+          <View
+            key={left}
+            style={{
+              position: 'absolute',
+              left,
+              top: -height,
+              width: 1,
+              height: height * 3,
+              backgroundColor: '#d97706',
+              transform: [{ rotate: '45deg' }],
+            }}
+          />
+        );
+      })}
+    </View>
+  );
+}

package/src/components/schedule/index.tsx

@@ -0,0 +1,109 @@
+import { Fragment } from 'react';
+import { View } from 'react-native';
+import { RosterGap } from '../layers/parts/gap';
+import { RosterInterval } from '../layers/parts/interval';
+import { regionStyle } from '../primitives/region-style';
+import { ScheduleDay } from './days/day';
+import { ScheduleDayHeaderLayout } from './days/header-layout';
+import { ScheduleColumn } from './days/parts/column';
+import { ScheduleDayHeader } from './days/parts/day-header';
+import { ScheduleGrid } from './days/parts/grid';
+import { ScheduleNowLine } from './days/parts/now-line';
+import { ScheduleSkippedDate } from './days/parts/skipped-date';
+import { ScheduleTransition } from './days/parts/transition';
+import { ScheduleLayout } from './layout';
+import { ScheduleGutter } from './parts/gutter';
+import { ScheduleIncomplete } from './parts/incomplete';
+import type { ScheduleProps } from './schedule.types';
+import { useSchedule } from './use-schedule';
+import { ScheduleWidth, useScheduleViewport } from './use-schedule-viewport';
+import { headerDates, nowPosition } from './utils/days';
+
+const hours = Array.from({ length: 24 }, (_, hour) => hour);
+
+export function Schedule(props: ScheduleProps) {
+  const { width, onLayout } = useScheduleViewport();
+  // Wait for measurement so the first mounted projection is the actual viewport key.
+  const content =
+    width === null ? null : (
+      <ScheduleWidth.Provider value={width}>
+        <ScheduleContent {...props} />
+      </ScheduleWidth.Provider>
+    );
+  return (
+    <View
+      onLayout={onLayout}
+      style={regionStyle(
+        { flex: 1, minHeight: 0, minWidth: 0, overflow: 'hidden' },
+        { backgroundColor: '#fff' },
+        props.style,
+      )}
+    >
+      {content}
+    </View>
+  );
+}
+
+function ScheduleContent(props: ScheduleProps) {
+  const { days, projection, geometry, now, press } = useSchedule(props);
+  const {
+    lane,
+    windowSpec,
+    highlightSource,
+    gutterZone = ScheduleGutter,
+    dayHeaderZone = ScheduleDayHeader,
+    skippedDateZone = ScheduleSkippedDate,
+    columnZone = ScheduleColumn,
+    gridZone = ScheduleGrid,
+    transitionZone = ScheduleTransition,
+    nowLineZone = ScheduleNowLine,
+    intervalZone = RosterInterval,
+    gapZone = RosterGap,
+    incompleteZone = ScheduleIncomplete,
+    incompleteLabel = 'Availability may be incomplete',
+  } = props;
+  const position = nowPosition(projection, now);
+  const incomplete =
+    lane.complete === false ? incompleteZone({ lane, label: incompleteLabel }) : null;
+  return (
+    <ScheduleLayout
+      headerStyle={props.headerStyle}
+      gutterStyle={props.gutterStyle}
+      daysStyle={props.daysStyle}
+      incompleteZone={incomplete}
+      gutterZone={gutterZone({ hours, pxPerHour: projection.pxPerHour })}
+      dayHeaderZone={headerDates(windowSpec, days).map(({ localDate, day }) => {
+        if (!day) return <Fragment key={localDate}>{skippedDateZone({ localDate })}</Fragment>;
+        return (
+          <ScheduleDayHeaderLayout
+            key={localDate}
+            width={projection.columnWidth}
+            headerZone={dayHeaderZone({ day })}
+          />
+        );
+      })}
+      daysZone={days.map((day, column) => {
+        const nowLine = position?.column === column ? nowLineZone(position) : null;
+        return (
+          <ScheduleDay
+            key={day.localDate}
+            day={day}
+            column={column}
+            lane={lane}
+            projection={projection}
+            geometry={geometry}
+            highlightSource={highlightSource}
+            hours={hours}
+            press={(x, y) => press(column, x, y)}
+            gridZone={gridZone}
+            columnZone={columnZone}
+            transitionZone={transitionZone}
+            intervalZone={intervalZone}
+            gapZone={gapZone}
+            nowLineZone={nowLine}
+          />
+        );
+      })}
+    />
+  );
+}

package/src/components/schedule/layout.tsx

@@ -0,0 +1,42 @@
+import type { ReactNode } from 'react';
+import { ScrollView, View } from 'react-native';
+import { regionStyle } from '../primitives/region-style';
+import type { ScheduleStyleProps } from './schedule.types';
+
+type ScheduleLayoutProps = Pick<ScheduleStyleProps, 'headerStyle' | 'gutterStyle' | 'daysStyle'> & {
+  /** Frozen day headings, including markers for wholly skipped local dates. */
+  dayHeaderZone: ReactNode;
+  /** Hour labels in a 48 px left gutter; shares the body's vertical scroll. */
+  gutterZone: ReactNode;
+  /** Day columns, each containing its grid, rects, transitions, and current-time line. */
+  daysZone: ReactNode;
+  /** Completeness notice in reserved empty space above the grid. */
+  incompleteZone: ReactNode;
+};
+
+export function ScheduleLayout({
+  dayHeaderZone,
+  gutterZone,
+  daysZone,
+  incompleteZone,
+  headerStyle,
+  gutterStyle,
+  daysStyle,
+}: ScheduleLayoutProps) {
+  return (
+    <View style={{ flex: 1, minHeight: 0 }}>
+      <View style={regionStyle({ marginLeft: 48, flexDirection: 'row' }, {}, headerStyle)}>
+        {dayHeaderZone}
+      </View>
+      <View>{incompleteZone}</View>
+      <ScrollView testID="schedule-vertical-scroll" horizontal={false} style={{ flex: 1 }}>
+        <View style={{ flexDirection: 'row' }}>
+          <View style={regionStyle({ width: 48 }, {}, gutterStyle)}>{gutterZone}</View>
+          <View style={regionStyle({ flex: 1, minWidth: 0, flexDirection: 'row' }, {}, daysStyle)}>
+            {daysZone}
+          </View>
+        </View>
+      </ScrollView>
+    </View>
+  );
+}

package/src/components/schedule/parts/gutter.tsx

@@ -0,0 +1,16 @@
+import { Text, View } from 'react-native';
+import type { ScheduleHoursInput } from '../schedule.types';
+
+export function ScheduleGutter({ hours, pxPerHour }: ScheduleHoursInput) {
+  return (
+    <View>
+      {hours.map((hour) => (
+        <View key={hour} style={{ height: pxPerHour }}>
+          <Text style={{ fontSize: 10, color: '#64748b', padding: 3 }}>
+            {String(hour).padStart(2, '0')}:00
+          </Text>
+        </View>
+      ))}
+    </View>
+  );
+}

package/src/components/schedule/parts/incomplete.tsx

@@ -0,0 +1,13 @@
+import { Text } from 'react-native';
+import type { Lane } from '../../../core';
+
+export function ScheduleIncomplete({ lane, label }: { lane: Lane; label: string }) {
+  return (
+    <Text
+      accessibilityLabel={`${lane.label}: ${label}`}
+      style={{ padding: 8, color: '#9a3412', fontSize: 12 }}
+    >
+      {label}
+    </Text>
+  );
+}

package/src/components/schedule/schedule.types.ts

@@ -0,0 +1,103 @@
+import type { ReactNode } from 'react';
+import type { StyleProp, ViewStyle } from 'react-native';
+import type {
+  DayColumn,
+  Lane,
+  LaneGeometry,
+  Projection,
+  Rect,
+  Source,
+  Transition,
+  Window,
+  WindowSpec,
+} from '../../core';
+import type { GapInput, IntervalInput } from '../layers/layers.types';
+
+export type ScheduleWindowSpec = WindowSpec & { span: 'day' | 'week' };
+export type ScheduleProjection = Extract<Projection, { orientation: 'columns' }>;
+export type ScheduleInput = {
+  lane: Lane;
+  windowSpec: ScheduleWindowSpec;
+  minuteStep?: number;
+  /** Positive finite pixels per wall-clock hour; defaults to 48. */
+  pxPerHour?: number;
+  highlightSource?: Source;
+  onNavigate?: (next: WindowSpec) => void;
+  onIntervalPress?: (rect: Rect, lane: Lane) => void;
+  onGapPress?: (rect: Rect, lane: Lane) => void;
+  onCellPress?: (lane: Lane, time: number) => void;
+};
+export type ScheduleModel = {
+  window: Window;
+  days: DayColumn[];
+  projection: ScheduleProjection;
+  geometry: LaneGeometry;
+  now: number | null;
+  press: (columnIndex: number, x: number, y: number) => void;
+  status: 'ready';
+};
+export type ScheduleTransitionInput = {
+  day: DayColumn;
+  transition: Transition;
+  /** Projected transition instant, separating repeated occurrences. */
+  dividerY: number;
+  y: number;
+  height: number;
+  width: number;
+};
+export type ScheduleColumnInput = {
+  day: DayColumn;
+  rects: Rect[];
+  gapRects: Rect[];
+  lane: Lane;
+  highlightSource?: Source;
+  press: (x: number, y: number) => void;
+  /** Covered rect filler shared with Roster; final bounds and stacking belong to the rect. */
+  intervalZone: (input: IntervalInput) => ReactNode;
+  /** Removed rect content shared with Roster; the column supplies its pressable bounds. */
+  gapZone: (input: GapInput) => ReactNode;
+};
+export type ScheduleHoursInput = { hours: number[]; pxPerHour: number };
+/**
+ * Chrome style props and their NativeWind class twins. Class props resolve only
+ * after `react-native-roster/nativewind` registers the component; without that
+ * entry they are ignored.
+ */
+export type ScheduleStyleProps = {
+  /** Outer measured container. */
+  style?: StyleProp<ViewStyle>;
+  className?: string;
+  /** Frozen day heading row, indented past the 48 px gutter. */
+  headerStyle?: StyleProp<ViewStyle>;
+  headerClassName?: string;
+  /** Scrolling 48 px hour gutter. */
+  gutterStyle?: StyleProp<ViewStyle>;
+  gutterClassName?: string;
+  /** Scrolling day column container beside the gutter. */
+  daysStyle?: StyleProp<ViewStyle>;
+  daysClassName?: string;
+};
+export type ScheduleProps = ScheduleInput &
+  ScheduleStyleProps & {
+    incompleteLabel?: string;
+    /** Frozen left hour labels; ScheduleGutter receives hours 0 through 23 and their scale. */
+    gutterZone?: (input: ScheduleHoursInput) => ReactNode;
+    /** Hour bands behind each day's rects; ScheduleGrid draws 24 bordered bands. */
+    gridZone?: (input: ScheduleHoursInput) => ReactNode;
+    /** Frozen day heading; ScheduleDayHeader shows weekday, localDate, and a transition badge. */
+    dayHeaderZone?: (input: { day: DayColumn }) => ReactNode;
+    /** Wholly skipped local date marker; ScheduleSkippedDate labels its zero-width header gap. */
+    skippedDateZone?: (input: { localDate: string }) => ReactNode;
+    /** The day's covered and removed rects; ScheduleColumn draws final bounds in layer order. */
+    columnZone?: (input: ScheduleColumnInput) => ReactNode;
+    /** Transition chrome only; ScheduleTransition hatches skips and divides repeats with again. */
+    transitionZone?: (input: ScheduleTransitionInput) => ReactNode;
+    /** Current day's line at y; ScheduleNowLine spans the containing column. */
+    nowLineZone?: (input: { y: number; column: number }) => ReactNode;
+    /** Covered rect filler shared with Roster; position using rect bounds and use pointerEvents="none". */
+    intervalZone?: (input: IntervalInput) => ReactNode;
+    /** Removed rect content shared with Roster; ScheduleColumn supplies the invisible pressable. */
+    gapZone?: (input: GapInput) => ReactNode;
+    /** Completeness notice in reserved empty space above the day grid; receives the lane and localized label. */
+    incompleteZone?: (input: { lane: Lane; label: string }) => ReactNode;
+  };

package/src/components/schedule/use-schedule-viewport.ts

@@ -0,0 +1,13 @@
+import { createContext, useState } from 'react';
+import type { LayoutChangeEvent } from 'react-native';
+
+// Standalone hooks use a 280 px grid; the chassis supplies its measured grid width.
+export const ScheduleWidth = createContext(280);
+
+export function useScheduleViewport() {
+  const [width, setWidth] = useState<number | null>(null);
+  function onLayout({ nativeEvent: { layout } }: LayoutChangeEvent) {
+    setWidth(Math.max(0, layout.width - 48));
+  }
+  return { width, onLayout };
+}

package/src/components/schedule/use-schedule.ts

@@ -0,0 +1,75 @@
+import { useContext, useEffect, useRef, useState } from 'react';
+import { dayColumnsFor, layoutLane, snapToStep, timeAtY, windowFor } from '../../core';
+import { hitTest } from '../../core/hit-test';
+import type { ScheduleInput, ScheduleModel, ScheduleProjection } from './schedule.types';
+import { ScheduleWidth } from './use-schedule-viewport';
+
+export function useSchedule(input: ScheduleInput): ScheduleModel {
+  const { lane, windowSpec, minuteStep = 60, pxPerHour = 48 } = input;
+  const width = useContext(ScheduleWidth);
+  const [clock, setClock] = useState(Date.now);
+  // The current-time indicator follows the wall clock for the mounted surface's lifetime.
+  useEffect(() => {
+    const timer = setInterval(() => setClock(Date.now()), 60_000);
+    return () => clearInterval(timer);
+  }, []);
+  if (!Number.isInteger(minuteStep) || minuteStep <= 0 || 60 % minuteStep !== 0)
+    throw new RangeError('minuteStep must be a positive divisor of 60');
+  if (!Number.isFinite(pxPerHour) || pxPerHour <= 0)
+    throw new RangeError('pxPerHour must be a positive finite number');
+  const window = windowFor(windowSpec);
+  const days = dayColumnsFor(window, windowSpec.timezone);
+  const projection: ScheduleProjection = {
+    orientation: 'columns',
+    viewTimezone: windowSpec.timezone,
+    pxPerHour,
+    columnWidth: width / Math.max(1, days.length),
+    days,
+  };
+  const geometry = layoutLane(lane, window, projection);
+  const currentPress = { input, window, projection, geometry };
+  const pressInput = useRef(currentPress);
+  pressInput.current = currentPress;
+  const [press] = useState(() => {
+    return function press(columnIndex: number, x: number, y: number): void {
+      const { input, window, projection, geometry } = pressInput.current;
+      const { lane, minuteStep = 60, onIntervalPress, onGapPress, onCellPress } = input;
+      if (!Number.isFinite(x) || !Number.isFinite(y) || x < 0 || x >= projection.columnWidth)
+        return;
+      const absolute = timeAtY(projection, columnIndex, y);
+      if (absolute === null) return;
+      const time = Math.max(
+        window.start,
+        snapToStep(absolute, minuteStep, projection.viewTimezone),
+      );
+      const hit = hitTest(
+        lane,
+        {
+          ...geometry,
+          rects: geometry.rects.filter((rect) => rect.column === columnIndex),
+          gapRects: geometry.gapRects.filter((rect) => rect.column === columnIndex),
+        },
+        x,
+        y,
+      );
+      if (hit?.kind === 'interval') {
+        onIntervalPress?.(hit.rect, lane);
+        return;
+      }
+      if (hit?.kind === 'gap') {
+        onGapPress?.(hit.rect, lane);
+        return;
+      }
+      if (time < window.end) onCellPress?.(lane, time);
+    };
+  });
+  return {
+    window,
+    days,
+    projection,
+    geometry,
+    now: clock >= window.start && clock < window.end ? clock : null,
+    press,
+    status: 'ready',
+  };
+}

package/src/components/schedule/utils/days.ts

@@ -0,0 +1,54 @@
+import type { DayColumn, Transition } from '../../../core';
+import { scalePieces } from '../../../core/scale';
+import { dateEpoch, dateString, dayMilliseconds, wallTime } from '../../../core/zone';
+import type { ScheduleProjection, ScheduleWindowSpec } from '../schedule.types';
+
+export function transitionBounds(
+  day: DayColumn,
+  transition: Transition,
+  projection: ScheduleProjection,
+) {
+  const minute =
+    (wallTime(transition.at, projection.viewTimezone) - dateEpoch(day.localDate)) / 60_000;
+  const delta = transition.deltaMinutes;
+  const start = Math.max(0, delta > 0 ? minute - delta : minute);
+  const end = Math.min(1440, delta < 0 ? minute - delta : minute);
+  const pxPerMinute = projection.pxPerHour / 60;
+  const y = start * pxPerMinute;
+  return {
+    y,
+    dividerY: nowPosition(projection, transition.at)?.y ?? y,
+    height: Math.max(0, end - start) * pxPerMinute,
+    width: projection.columnWidth,
+  };
+}
+
+export function nowPosition(projection: ScheduleProjection, now: number | null) {
+  if (now !== null) {
+    for (const [column, day] of projection.days.entries()) {
+      for (const piece of scalePieces(day, projection.viewTimezone)) {
+        if (now >= piece.start && now < piece.end)
+          return {
+            column,
+            y:
+              ((piece.minute + ((now - piece.start) / 60_000) * piece.scale) *
+                projection.pxPerHour) /
+              60,
+          };
+      }
+    }
+  }
+  return null;
+}
+
+export function headerDates(spec: ScheduleWindowSpec, days: DayColumn[]) {
+  let start = dateEpoch(spec.anchorDate);
+  if (spec.span === 'week') {
+    const weekday = (new Date(start).getUTCDay() + 6) % 7;
+    start -= ((weekday - (spec.wkst ?? 0) + 7) % 7) * dayMilliseconds;
+  }
+  return Array.from({ length: spec.span === 'week' ? 7 : 1 }, (_, index) => {
+    const localDate = dateString(start + index * dayMilliseconds);
+    return { localDate, day: days.find((day) => day.localDate === localDate) };
+  });
+}

package/src/core/README.md

@@ -0,0 +1,25 @@
+# core
+
+Pure types and geometry. Imports only standard JavaScript and `Intl`; no React,
+no React Native, no dependencies.
+
+- Public subpath: `react-native-roster/core`; the root entry re-exports it
+- Authoritative types: `types.ts` (`Lane`, `Layer`, `Interval`, `Gap`,
+  `Source`, `Window`, `Projection`, `Rect`, `Coverage`, `LaneGeometry`)
+- Barrel: `index.ts` only
+
+| File | Role |
+| --- | --- |
+| `axis.ts` | window specs, spans, and navigation (`windowFor`, `next`, `prev`, `today`) |
+| `layout.ts` | rect geometry for one lane in either projection |
+| `coverage.ts` | covered and removed minutes per lane |
+| `spans.ts` | the provenance sweep: exact sources per merged span |
+| `columns.ts` | day columns, transitions, and skipped dates for the columns projection |
+| `zone.ts` | Intl-only timezone math (offsets, first instants, transitions) |
+| `scale.ts`, `snap.ts` | pixel and time conversion, pointer snapping |
+| `hit-test.ts` | the geometry walk both hooks use to resolve a press |
+| `order.ts`, `flag.ts` | lane comparators and lane flags |
+| `cache.ts`, `hash.ts` | layout and coverage caches keyed by lane content |
+
+Reference: [design](../../docs/design.md), [timezones](../../docs/timezones.md),
+[caches](../../docs/caches.md). Tests: `test/core`.

package/src/core/axis.ts

@@ -0,0 +1,58 @@
+import type { Weekday, Window } from './types';
+import { dateEpoch, dateString, dayMilliseconds, localDateAt, startOfDate } from './zone';
+
+export type Span = 'day' | 'week' | 'month';
+/** The anchor is a local calendar date in `timezone`, not an instant, so a zone change keeps the same local week. */
+export type WindowSpec =
+  | { span: Span; anchorDate: string; wkst?: Weekday; timezone: string }
+  | { span: 'custom'; window: Window; timezone: string };
+
+export function windowFor(spec: WindowSpec): Window {
+  if (spec.span === 'custom') return spec.window;
+  const date = new Date(dateEpoch(spec.anchorDate));
+  if (spec.span === 'week') {
+    const weekday = (date.getUTCDay() + 6) % 7;
+    date.setUTCDate(date.getUTCDate() - ((weekday - (spec.wkst ?? 0) + 7) % 7));
+  }
+  if (spec.span === 'month') date.setUTCDate(1);
+  const start = startOfDate(dateString(date.getTime()), spec.timezone);
+  if (spec.span === 'month') date.setUTCMonth(date.getUTCMonth() + 1);
+  else date.setUTCDate(date.getUTCDate() + (spec.span === 'week' ? 7 : 1));
+  return { start, end: startOfDate(dateString(date.getTime()), spec.timezone) };
+}
+
+export function prev(spec: WindowSpec): WindowSpec {
+  return move(spec, -1);
+}
+
+export function next(spec: WindowSpec): WindowSpec {
+  return move(spec, 1);
+}
+
+export function today(spec: WindowSpec): WindowSpec {
+  const anchorDate = localDateAt(Date.now(), spec.timezone);
+  if (spec.span !== 'custom') return { ...spec, anchorDate };
+  const start = startOfDate(anchorDate, spec.timezone);
+  return { ...spec, window: { start, end: start + spec.window.end - spec.window.start } };
+}
+
+function move(spec: WindowSpec, direction: number): WindowSpec {
+  if (spec.span === 'custom') {
+    const delta = direction * (spec.window.end - spec.window.start);
+    return { ...spec, window: { start: spec.window.start + delta, end: spec.window.end + delta } };
+  }
+  const time = dateEpoch(spec.anchorDate);
+  if (spec.span !== 'month') {
+    return {
+      ...spec,
+      anchorDate: dateString(time + direction * (spec.span === 'week' ? 7 : 1) * dayMilliseconds),
+    };
+  }
+  const date = new Date(time);
+  const day = date.getUTCDate();
+  date.setUTCDate(1);
+  date.setUTCMonth(date.getUTCMonth() + direction + 1);
+  date.setUTCDate(0);
+  date.setUTCDate(Math.min(day, date.getUTCDate()));
+  return { ...spec, anchorDate: dateString(date.getTime()) };
+}

package/src/core/cache.ts

@@ -0,0 +1,38 @@
+import type { Coverage, LaneFlag, LaneGeometry, Rect } from './types';
+
+export const layoutCache = new Map<
+  string,
+  {
+    rects: Rect[];
+    gapRects: Rect[];
+    assemblies: WeakMap<Coverage, Map<LaneFlag, LaneGeometry>>;
+  }
+>();
+export const coverageCache = new Map<string, Coverage>();
+export const counts = {
+  layout: { runs: 0, cacheHits: 0 },
+  coverage: { runs: 0, cacheHits: 0 },
+};
+
+export function layoutStats(): { runs: number; cacheHits: number } {
+  return { ...counts.layout };
+}
+
+export function coverageStats(): { runs: number; cacheHits: number } {
+  return { ...counts.coverage };
+}
+
+export function resetStats(): void {
+  counts.layout.runs = 0;
+  counts.layout.cacheHits = 0;
+  counts.coverage.runs = 0;
+  counts.coverage.cacheHits = 0;
+}
+
+export function clearLayoutCache(): void {
+  layoutCache.clear();
+}
+
+export function clearCoverageCache(): void {
+  coverageCache.clear();
+}