react-native-ruler-date-picker 0.1.0

package/src/defaults.ts

@@ -0,0 +1,44 @@
+import type { ResolvedColors } from './types';
+
+// ── Internal constants (not user-configurable) ───────────────────────────
+export const MS_PER_DAY = 86_400_000;
+export const DEFAULT_DAY_RANGE = 365;
+
+// ── User-configurable defaults ───────────────────────────────────────────
+export const DEFAULTS = {
+  tickSpacing: 24,
+  tickHeight: 12,
+  tickTallHeight: 24,
+  tickThickness: 4,
+  height: 120,
+  rulerHeight: 60,
+  indicatorWidth: 2,
+  indicatorHeight: 40,
+  todayDotSize: 6,
+  labelFontSize: 10,
+  bufferTicks: 10,
+  updateDebounceMs: 100,
+  fastSwipeTickThreshold: 1,
+  continuousHapticIntervalMs: 20,
+  enableHaptics: true,
+  showResetToToday: false,
+} as const;
+
+// ── Default color palettes ───────────────────────────────────────────────
+export const LIGHT_COLORS: ResolvedColors = {
+  tickColor: '#D1D5DB',
+  tickTallColor: '#9CA3AF',
+  labelColor: '#6B7280',
+  accentColor: '#3B82F6',
+  indicatorColor: '#3B82F6',
+  backgroundColor: 'transparent',
+};
+
+export const DARK_COLORS: ResolvedColors = {
+  tickColor: '#4B5563',
+  tickTallColor: '#6B7280',
+  labelColor: '#9CA3AF',
+  accentColor: '#60A5FA',
+  indicatorColor: '#60A5FA',
+  backgroundColor: 'transparent',
+};

package/src/index.ts

@@ -0,0 +1,2 @@
+export { RulerDatePicker } from './RulerDatePicker';
+export type { RulerDatePickerProps } from './types';

package/src/types.ts

@@ -0,0 +1,129 @@
+import type React from 'react';
+
+export interface RulerDatePickerProps {
+  // ── Selection & Bounds ─────────────────────────────────────
+  /** The currently selected date. Accepts a Date object or a YYYY-MM-DD string. */
+  selectedDate: Date | string;
+  /**
+   * Called when the user scrolls to a new date.
+   * Provides both the Date object and the formatted YYYY-MM-DD string.
+   */
+  onSelectDate: (date: Date, dateString: string) => void;
+  /** Minimum selectable date. Defaults to 365 days before today. */
+  minDate?: Date;
+  /** Maximum selectable date. Defaults to 365 days after today. */
+  maxDate?: Date;
+
+  // ── Label & Highlight Rules ────────────────────────────────
+  /**
+   * Controls which ticks show a date label.
+   * - `'daily'` — every tick gets a label
+   * - `'weekly'` (default) — every 7th day
+   * - `'monthly'` — 1st of each month
+   * - `(date: Date) => boolean` — custom callback
+   */
+  labelInterval?: 'daily' | 'weekly' | 'monthly' | ((date: Date) => boolean);
+  /** Days of the week to visually highlight. 0 = Sunday, 6 = Saturday. e.g. [0, 6] for weekends. */
+  highlightDays?: number[];
+
+  // ── Tick Dimensions ────────────────────────────────────────
+  /** Gap between ticks in pixels. Default: 24 */
+  tickSpacing?: number;
+  /** Height of small (unlabeled) ticks in pixels. Default: 12 */
+  tickHeight?: number;
+  /** Height of tall (labeled) ticks in pixels. Default: 24 */
+  tickTallHeight?: number;
+  /** Width of each tick bar in pixels. Default: 4 */
+  tickThickness?: number;
+
+  // ── Tick Colors (small & large independently) ──────────────
+  /** Color of small (unlabeled) ticks. */
+  tickColor?: string;
+  /** Color of tall (labeled) ticks. Falls back to tickColor if not specified. */
+  tickTallColor?: string;
+
+  // ── Label & Accent Colors ─────────────────────────────────
+  /** Color of date label text beneath labeled ticks. */
+  labelColor?: string;
+  /** Color of the today dot indicator and reset button text. */
+  accentColor?: string;
+  /** Color of the center selection indicator line. */
+  indicatorColor?: string;
+  /** Background color of the entire component. Default: transparent */
+  backgroundColor?: string;
+
+  // ── Layout Dimensions ─────────────────────────────────────
+  /** Total component height in pixels. Default: 120 */
+  height?: number;
+  /** Height of the ruler track area in pixels. Default: 60 */
+  rulerHeight?: number;
+  /** Width of the center selection indicator bar in pixels. Default: 2 */
+  indicatorWidth?: number;
+  /** Height of the center selection indicator bar in pixels. Default: 40 */
+  indicatorHeight?: number;
+  /** Diameter of the today dot indicator in pixels. Default: 6 */
+  todayDotSize?: number;
+  /** Font size of tick date labels in pixels. Default: 10 */
+  labelFontSize?: number;
+
+  // ── Performance Tuning ────────────────────────────────────
+  /** Number of off-screen ticks to render as buffer on each side. Default: 10 */
+  bufferTicks?: number;
+  /** Debounce interval in ms before calling onSelectDate. Default: 100 */
+  updateDebounceMs?: number;
+
+  // ── Haptic Tuning ─────────────────────────────────────────
+  /** Enable or disable haptic feedback. Default: true */
+  enableHaptics?: boolean;
+  /**
+   * Custom haptic trigger callback. When provided, overrides the default
+   * expo-haptics implementation. Receives the haptic mode:
+   * - `'tick'` — single discrete haptic (slow scrolling)
+   * - `'continuous'` — continuous buzz (fast scrolling)
+   */
+  onHapticTrigger?: (mode: 'tick' | 'continuous') => void;
+  /** Number of ticks crossed per frame to trigger fast/continuous haptic mode. Default: 1 */
+  fastSwipeTickThreshold?: number;
+  /** Interval in ms between haptic pulses in continuous mode. Default: 20 */
+  continuousHapticIntervalMs?: number;
+
+  // ── Reset Control ─────────────────────────────────────────
+  /** Show a "Today" reset button when not on today's date. Default: false */
+  showResetToToday?: boolean;
+
+  // ── Custom Renderers ──────────────────────────────────────
+  /**
+   * Custom header renderer. When provided, replaces the default date header.
+   * Receives the selected date, whether it's today, and a function to reset to today.
+   */
+  renderHeader?: (
+    selectedDate: Date,
+    isToday: boolean,
+    resetToToday: () => void
+  ) => React.ReactNode;
+}
+
+/**
+ * Internal type for resolved color values.
+ * @internal
+ */
+export interface ResolvedColors {
+  tickColor: string;
+  tickTallColor: string;
+  labelColor: string;
+  accentColor: string;
+  indicatorColor: string;
+  backgroundColor: string;
+}
+
+/**
+ * Internal tick data used for rendering.
+ * @internal
+ */
+export interface TickData {
+  offset: number;
+  isLabeled: boolean;
+  isToday: boolean;
+  isHighlighted: boolean;
+  dateStr: string;
+}

package/src/useHaptics.ts

@@ -0,0 +1,107 @@
+import { useCallback, useRef } from 'react';
+import { Platform } from 'react-native';
+import { DEFAULTS } from './defaults';
+
+/**
+ * Attempts to dynamically require expo-haptics.
+ * Returns null if the module is not installed, allowing graceful degradation
+ * in pure React Native CLI projects.
+ */
+let ExpoHaptics: typeof import('expo-haptics') | null = null;
+try {
+  ExpoHaptics = require('expo-haptics');
+} catch {
+  // expo-haptics not installed — haptics will be silently disabled
+}
+
+interface UseHapticsOptions {
+  enableHaptics: boolean;
+  onHapticTrigger?: (mode: 'tick' | 'continuous') => void;
+  continuousHapticIntervalMs: number;
+}
+
+interface HapticsAPI {
+  fireDiscreteHaptic: () => void;
+  startContinuousHaptic: () => void;
+  stopContinuousHaptic: () => void;
+}
+
+/**
+ * Haptics abstraction hook.
+ *
+ * - If `onHapticTrigger` is provided, delegates all haptic calls to it.
+ * - Otherwise, uses expo-haptics if available.
+ * - Falls back to no-op if neither is available or haptics are disabled.
+ */
+export function useHaptics({
+  enableHaptics,
+  onHapticTrigger,
+  continuousHapticIntervalMs = DEFAULTS.continuousHapticIntervalMs,
+}: UseHapticsOptions): HapticsAPI {
+  const hapticIntervalRef = useRef<ReturnType<typeof setInterval> | null>(
+    null
+  );
+
+  /** Fire a single discrete haptic — used in slow scroll mode */
+  const fireDiscreteHaptic = useCallback(() => {
+    if (!enableHaptics) return;
+
+    if (onHapticTrigger) {
+      onHapticTrigger('tick');
+      return;
+    }
+
+    if (!ExpoHaptics) return;
+
+    if (Platform.OS === 'android') {
+      ExpoHaptics.impactAsync(ExpoHaptics.ImpactFeedbackStyle.Light).catch(
+        () => {}
+      );
+    } else {
+      ExpoHaptics.selectionAsync().catch(() => {});
+    }
+  }, [enableHaptics, onHapticTrigger]);
+
+  /** Start a continuous haptic buzz — used in fast scroll mode */
+  const startContinuousHaptic = useCallback(() => {
+    if (!enableHaptics) return;
+
+    if (onHapticTrigger) {
+      onHapticTrigger('continuous');
+      return;
+    }
+
+    if (!ExpoHaptics) return;
+
+    // Already running — don't double-start
+    if (hapticIntervalRef.current) return;
+
+    // Fire one immediately so the transition isn't silent
+    ExpoHaptics.impactAsync(ExpoHaptics.ImpactFeedbackStyle.Light).catch(
+      () => {}
+    );
+
+    const interval =
+      Platform.OS === 'android' ? 35 : continuousHapticIntervalMs;
+
+    hapticIntervalRef.current = setInterval(() => {
+      ExpoHaptics!.impactAsync(ExpoHaptics!.ImpactFeedbackStyle.Light).catch(
+        () => {}
+      );
+    }, interval);
+  }, [enableHaptics, onHapticTrigger, continuousHapticIntervalMs]);
+
+  /** Stop the continuous haptic buzz */
+  const stopContinuousHaptic = useCallback(() => {
+    if (hapticIntervalRef.current) {
+      clearInterval(hapticIntervalRef.current);
+      hapticIntervalRef.current = null;
+    }
+  }, []);
+
+  return {
+    fireDiscreteHaptic,
+    startContinuousHaptic,
+    stopContinuousHaptic,
+  };
+}

package/src/utils.ts

@@ -0,0 +1,115 @@
+import { useColorScheme } from 'react-native';
+import { LIGHT_COLORS, DARK_COLORS, MS_PER_DAY, DEFAULT_DAY_RANGE } from './defaults';
+import type { RulerDatePickerProps, ResolvedColors } from './types';
+
+/**
+ * Formats a Date object as a local YYYY-MM-DD string,
+ * avoiding timezone shifting bugs caused by toISOString().
+ */
+export function formatDateString(date: Date = new Date()): string {
+  const year = date.getFullYear();
+  const month = String(date.getMonth() + 1).padStart(2, '0');
+  const day = String(date.getDate()).padStart(2, '0');
+  return `${year}-${month}-${day}`;
+}
+
+/**
+ * Converts a Date or YYYY-MM-DD string to a day offset relative to a reference time.
+ */
+export function dateToDayOffset(
+  date: Date | string,
+  referenceTime: number
+): number {
+  const d = typeof date === 'string' ? new Date(date) : new Date(date);
+  d.setHours(0, 0, 0, 0);
+  return Math.round((d.getTime() - referenceTime) / MS_PER_DAY);
+}
+
+/**
+ * Converts a day offset back to a Date object.
+ */
+export function dayOffsetToDate(offset: number, referenceTime: number): Date {
+  return new Date(referenceTime + offset * MS_PER_DAY);
+}
+
+/**
+ * Resolves user-provided color props against the system color scheme defaults.
+ * User-provided values always take precedence.
+ */
+export function useResolvedColors(
+  props: Pick<
+    RulerDatePickerProps,
+    | 'tickColor'
+    | 'tickTallColor'
+    | 'labelColor'
+    | 'accentColor'
+    | 'indicatorColor'
+    | 'backgroundColor'
+  >
+): ResolvedColors {
+  const scheme = useColorScheme();
+  const palette = scheme === 'dark' ? DARK_COLORS : LIGHT_COLORS;
+
+  return {
+    tickColor: props.tickColor ?? palette.tickColor,
+    tickTallColor: props.tickTallColor ?? props.tickColor ?? palette.tickTallColor,
+    labelColor: props.labelColor ?? palette.labelColor,
+    accentColor: props.accentColor ?? palette.accentColor,
+    indicatorColor: props.indicatorColor ?? palette.indicatorColor,
+    backgroundColor: props.backgroundColor ?? palette.backgroundColor,
+  };
+}
+
+/**
+ * Determines whether a date should display a label based on the labelInterval setting.
+ */
+export function shouldShowLabel(
+  date: Date,
+  labelInterval: RulerDatePickerProps['labelInterval'],
+  todayTime: number
+): boolean {
+  if (!labelInterval || labelInterval === 'weekly') {
+    // Default: every 7th day relative to today (matches original Friday-style spacing)
+    const dayOffset = Math.round(
+      (date.getTime() - todayTime) / MS_PER_DAY
+    );
+    return dayOffset % 7 === 0;
+  }
+
+  if (labelInterval === 'daily') {
+    return true;
+  }
+
+  if (labelInterval === 'monthly') {
+    return date.getDate() === 1;
+  }
+
+  // Custom callback
+  return labelInterval(date);
+}
+
+/**
+ * Computes the min/max day offsets from props or defaults.
+ */
+export function computeDayRange(
+  todayTime: number,
+  minDate?: Date,
+  maxDate?: Date
+): { minOffset: number; maxOffset: number } {
+  let minOffset = -DEFAULT_DAY_RANGE;
+  let maxOffset = DEFAULT_DAY_RANGE;
+
+  if (minDate) {
+    const d = new Date(minDate);
+    d.setHours(0, 0, 0, 0);
+    minOffset = Math.round((d.getTime() - todayTime) / MS_PER_DAY);
+  }
+
+  if (maxDate) {
+    const d = new Date(maxDate);
+    d.setHours(0, 0, 0, 0);
+    maxOffset = Math.round((d.getTime() - todayTime) / MS_PER_DAY);
+  }
+
+  return { minOffset, maxOffset };
+}