cleanhaus-calendar 1.0.0 → 1.0.1

package/README.md

@@ -1,13 +1,8 @@
 # cleanhaus-calendar
 
-A production-ready, cross-platform calendar component for React Native and Next.js. Features Month, Week, and Day views with horizontal time positioning and multi-day event spanning.
+Cross-platform calendar component for React Native and Next.js with Month, Week, and Day views. Features horizontal time positioning, multi-day event spanning, and type-based event rendering.
 
-## 🚀 Platform Support
-
-- ✅ **React Native** (iOS/Android)
-- ✅ **Next.js** (Web with react-native-web)
-
-## 📦 Installation
+## Installation
 
 ```bash
 npm install cleanhaus-calendar
@@ -19,23 +14,24 @@ npm install cleanhaus-calendar
 npm install react react-native react-native-web react-native-reanimated dayjs calendarize
 ```
 
-**Requirements:**
-- `react`: >=18.0.0 (supports React 18 & 19)
-- `react-native`: >=0.70.0
-- `react-native-web`: >=0.19.0
-- `react-native-reanimated`: >=3.0.0
-- `dayjs`: ^1.11.0
-- `calendarize`: ^1.1.0
-- `node`: >=18.0.0
+**Compatibility:**
+- React >=18.0.0
+- React Native >=0.70.0
+- react-native-web >=0.19.0 (optional, for web)
+- react-native-reanimated >=3.0.0
+- dayjs ^1.11.0
+- calendarize ^1.1.0
+- Node >=18.0.0
 
-## ⚙️ Setup
+## Quick Start
 
-### React Native (Expo/RN)
+### React Native
 
-No additional configuration needed! Just install and use:
+No additional configuration needed. Install and use:
 
 ```tsx
 import { Calendar, CalendarEvent } from "cleanhaus-calendar";
+import { useState } from "react";
 
 const events: CalendarEvent[] = [
   {
@@ -48,24 +44,29 @@ const events: CalendarEvent[] = [
   },
 ];
 
-<Calendar
-  events={events}
-  view="month"
-  date={new Date()}
-  onDateChange={setDate}
-  onEventPress={(event) => console.log(event)}
-/>
+function App() {
+  const [date, setDate] = useState(new Date());
+
+  return (
+    <Calendar
+      events={events}
+      view="month"
+      date={date}
+      onDateChange={setDate}
+      onEventPress={(event) => {
+        // Handle event press
+      }}
+    />
+  );
+}
 ```
 
-### Next.js Setup
+### Next.js
 
-**1. Install dependencies:**
-```bash
-npm install cleanhaus-calendar react react-native react-native-web react-native-reanimated dayjs calendarize
-```
+**1. Configure Next.js:**
 
-**2. Update `next.config.ts`:**
 ```typescript
+// next.config.ts
 import type { NextConfig } from "next";
 
 const withCalendar = require("cleanhaus-calendar/next-plugin");
@@ -77,7 +78,10 @@ const nextConfig: NextConfig = {
 export default withCalendar(nextConfig);
 ```
 
-**3. Update `package.json` dev script (Next.js 16+):**
+**2. Development (Next.js 16+):**
+
+Next.js 16+ uses Turbopack by default for development, but this package requires webpack configuration. Use the `--webpack` flag during development:
+
 ```json
 {
   "scripts": {
@@ -86,105 +90,69 @@ export default withCalendar(nextConfig);
 }
 ```
 
-**4. Use the component:**
-```tsx
-"use client"; // Required for App Router
+**Note:** Production builds automatically use webpack, so no additional configuration is needed for deployment.
 
-import { Calendar, CalendarEvent } from "cleanhaus-calendar";
-import { useState } from "react";
-
-export default function MyPage() {
-  const [view, setView] = useState<ViewMode>("month");
-  const [date, setDate] = useState(new Date());
-
-  return (
-    <Calendar
-      events={events}
-      view={view}
-      date={date}
-      onDateChange={setDate}
-      onEventPress={(event) => console.log(event)}
-      onViewChange={setView}
-    />
-  );
-}
-```
-
-**Note:** Next.js 16+ uses Turbopack by default. The plugin requires webpack, so use `--webpack` flag.
-
-## 📖 Usage
-
-### Basic Example
+**3. Use the component:**
 
 ```tsx
+"use client";
+
 import { Calendar, CalendarEvent, ViewMode } from "cleanhaus-calendar";
 import { useState } from "react";
 
-const events: CalendarEvent[] = [
-  {
-    id: "1",
-    eventId: "property-1",
-    title: "Booking",
-    start: new Date(2025, 0, 15, 10, 0),
-    end: new Date(2025, 0, 20, 14, 0),
-    meta: { type: "property" },
-  },
-];
-
-function MyCalendar() {
+export default function CalendarPage() {
   const [view, setView] = useState<ViewMode>("month");
   const [date, setDate] = useState(new Date());
 
+  const events: CalendarEvent[] = [
+    {
+      id: "1",
+      eventId: "property-1",
+      title: "Booking",
+      start: new Date(2025, 0, 15, 10, 0),
+      end: new Date(2025, 0, 20, 14, 0),
+      meta: { type: "property" },
+    },
+  ];
+
   return (
     <Calendar
       events={events}
       view={view}
       date={date}
       onDateChange={setDate}
-      onEventPress={(event) => console.log(event)}
       onViewChange={setView}
+      onEventPress={(event) => {
+        // Handle event press
+      }}
     />
   );
 }
 ```
 
-### Custom Cleaning Icon
-
-The package includes a default sparkle icon (✨) for cleaning events. Override it:
-
-```tsx
-import sparksIcon from "./assets/sparks.png";
-
-<Calendar
-  events={events}
-  cleaningIcon={sparksIcon} // Optional: custom icon
-  // ... other props
-/>
-```
-
-## 🔄 Data Format
+## Data Format
 
 Events must follow this structure:
 
 ```typescript
 interface CalendarEvent {
-  id: string;              // Required: Unique identifier
-  eventId: string;         // Required: Group identifier (e.g., "property-1")
-  title: string;           // Required: Event title
-  start: Date;             // Required: Must be Date object (not string!)
-  end: Date;               // Required: Must be Date object (not string!)
+  id: string;              // Unique identifier
+  eventId: string;         // Group identifier (e.g., "property-1")
+  title: string;           // Event title
+  start: Date;             // Start date/time (must be Date object)
+  end: Date;               // End date/time (must be Date object)
   meta?: {
     type?: "property" | "cleaning" | "service" | "otherService" | "unassigned";
-    jobTypeId?: number;    // For cleaning: 1 = cleaning, 2-4 = service types
     [key: string]: any;
   };
 }
 ```
 
-### Transform API Data
+**Important:** Always convert date strings to `Date` objects. The component does not accept string dates.
+
+### Transforming API Data
 
 ```typescript
-// Transform API response to CalendarEvent format
 function transformApiEvents(apiData: ApiEvent[]): CalendarEvent[] {
   return apiData.map((item) => ({
     id: item.id.toString(),
@@ -199,77 +167,75 @@ function transformApiEvents(apiData: ApiEvent[]): CalendarEvent[] {
 }
 ```
 
-**Important:** Always convert date strings to `Date` objects. The component does not accept string dates.
+## API Reference
+
+### Calendar Props
 
-## 🎯 Key Props
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `events` | `CalendarEvent[]` | Yes | - | Array of events to display |
+| `date` | `Date` | Yes | - | Current date/month |
+| `onDateChange` | `(date: Date) => void` | Yes | - | Called when date changes |
+| `onEventPress` | `(event: CalendarEvent) => void` | Yes | - | Called when event is pressed |
+| `view` | `"month" \| "week" \| "day"` | No | `"month"` | View mode |
+| `onViewChange` | `(view: ViewMode) => void` | No | - | Called when view mode changes |
+| `onDateTimeChange` | `(dateTime: Date) => void` | No | - | Unified handler for date+time changes (navigates to day view) |
+| `isLoading` | `boolean` | No | `false` | Show loading spinner |
+| `theme` | `Partial<CalendarTheme>` | No | - | Custom theme override |
+| `availableProperties` | `Array<{ id: number }>` | No | - | Properties for consistent color assignment |
+| `propertiesToShow` | `Array<{ id: number; name?: string }>` | No | - | Properties to show in DayView lanes |
+| `propertyColors` | `string[]` | No | - | Custom property colors array |
+| `propertyColorsDark` | `string[]` | No | - | Custom dark property colors array |
+| `cleaningIcon` | `any` | No | - | Custom icon for cleaning events |
+| `showFAB` | `boolean` | No | `false` | Show floating action button |
+| `onFABPress` | `() => void` | No | - | FAB press handler |
+| `fabStyle` | `ViewStyle` | No | - | Custom FAB styles |
+| `renderFAB` | `() => React.ReactElement \| null` | No | - | Custom FAB component renderer |
+| `autoScrollToNow` | `boolean` | No | `false` | Auto-scroll to current time in day view |
 
-| Prop | Type | Required | Description |
-|------|------|----------|-------------|
-| `events` | `CalendarEvent[]` | Yes | Array of events |
-| `view` | `"month" \| "week" \| "day"` | No | View mode (default: `"month"`) |
-| `date` | `Date` | Yes | Current date/month |
-| `onDateChange` | `(date: Date) => void` | Yes | Date navigation handler |
-| `onEventPress` | `(event: CalendarEvent) => void` | Yes | Event press handler |
-| `onViewChange` | `(view: ViewMode) => void` | No | View mode change handler |
-| `cleaningIcon` | `any` | No | Custom icon for cleaning events |
-| `theme` | `CalendarTheme` | No | Custom theme |
-| `availableProperties` | `Property[]` | No | Properties for color assignment |
+### Exports
 
-See [full props reference](#props-reference) below.
+- `Calendar` - Main calendar component
+- `CalendarEvent` - Event type
+- `ViewMode` - View mode type (`"day" | "week" | "month"`)
+- `MonthView`, `WeekView`, `DayView` - Individual view components
+- `CalendarFAB` - Floating action button component
+- Utilities: `dateUtils`, `weekDayUtils`, `theme`, `propertyColors`
+- Hooks: `useSwipeGesture`
 
-## 🎨 Features
+## Features
 
 - **Month View**: Calendar grid with event bars and swipe navigation
 - **Week View**: 7-day view with time-based positioning
 - **Day View**: Single-day view with property lanes
 - **Multi-day Events**: Continuous bars across day cells
-- **Type-based Rendering**: Different styles for property, cleaning, service events
-- **Built-in Assets**: Default sparkle icon (✨) for cleaning events
-
-## 🐛 Troubleshooting
+- **Type-based Rendering**: Different styles for different event types
+- **Theme Customization**: Customizable colors and styles
+- **Cross-platform**: Works on React Native (iOS/Android) and Web (Next.js)
+- **SSR-safe**: Server-side rendering compatible
 
-### Events not appearing
-- ✅ Ensure `start` and `end` are `Date` objects (not strings)
-- ✅ Check `eventId` is set correctly
-- ✅ Verify `containerHeight` is sufficient (minimum 400px)
+## Troubleshooting
 
-### Next.js Issues
+**Events not appearing:**
+- Ensure `start` and `end` are `Date` objects (not strings)
+- Verify `eventId` is set correctly
+- Check that events fall within the visible date range
 
-**Module not found:**
-- ✅ Restart dev server: `npm run dev -- --webpack`
-- ✅ Clear cache: `rm -rf .next`
+**Next.js issues:**
+- Use `--webpack` flag for development: `npm run dev -- --webpack`
+- Clear Next.js cache: `rm -rf .next`
+- Ensure `react-native-web` is installed
+- Verify the plugin is correctly applied in `next.config.ts`
 
-**Element type is invalid:**
-- ✅ Ensure `--webpack` flag is used
-- ✅ Verify `react-native-web` is installed
-
-**Turbopack error:**
-- ✅ Use `npm run dev -- --webpack`
-- ✅ Or add `turbopack: {}` to `next.config.ts`
-
-## 📚 Props Reference
-
-### Calendar Props
-
-| Prop | Type | Required | Default | Description |
-|------|------|----------|---------|-------------|
-| `events` | `CalendarEvent[]` | Yes | - | Array of events |
-| `view` | `ViewMode` | No | `"month"` | View mode |
-| `date` | `Date` | Yes | - | Current date |
-| `onDateChange` | `(date: Date) => void` | Yes | - | Date change handler |
-| `onEventPress` | `(event: CalendarEvent) => void` | Yes | - | Event press handler |
-| `onViewChange` | `(view: ViewMode) => void` | No | - | View change handler |
-| `isLoading` | `boolean` | No | `false` | Show loading spinner |
-| `theme` | `CalendarTheme` | No | - | Custom theme |
-| `availableProperties` | `Property[]` | No | - | Properties for colors |
-| `cleaningIcon` | `any` | No | - | Custom cleaning icon |
-| `showFAB` | `boolean` | No | `false` | Show floating action button |
-| `autoScrollToNow` | `boolean` | No | `false` | Auto-scroll to current time |
+**Module not found errors:**
+- Restart the development server
+- Clear node_modules and reinstall: `rm -rf node_modules && npm install`
 
-## 📄 License
+## License
 
 MIT
 
----
+## Links
 
-**Version**: 1.0.0
+- [Repository](https://github.com/cleanhaus/calendar-component)
+- [Issues](https://github.com/cleanhaus/calendar-component/issues)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cleanhaus-calendar",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Cross-platform calendar component for React Native and Web",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -19,7 +19,7 @@
   "files": [
     "**/*.ts",
     "**/*.tsx",
-    "shared/**/*.png",
+    "src/shared/**/*.png",
     "README.md",
     "LICENSE",
     "CHANGELOG.md",

package/src/Calendar.tsx

@@ -1,5 +1,5 @@
 // React Native Calendar Component - Uses only RN components
-import React, { useState, useCallback } from "react";
+import React, { useState, useCallback, useEffect } from "react";
 import {
   StyleSheet,
   View,
@@ -7,6 +7,7 @@ import {
   Dimensions,
   ActivityIndicator,
 } from "react-native";
+import type { LayoutChangeEvent } from "react-native";
 import { CalendarProps, CalendarEvent } from "./types";
 import { MonthView } from "./MonthView";
 import { DayView } from "./DayView";
@@ -18,6 +19,7 @@ import {
   DEFAULT_PROPERTY_COLORS,
   DEFAULT_PROPERTY_COLORS_DARK,
 } from "./utils/propertyColors";
+import { validateCalendarProps, logValidationErrors } from "./utils/validation";
 
 export const CustomCalendar: React.FC<CalendarProps> = ({
   events = [],
@@ -40,6 +42,20 @@ export const CustomCalendar: React.FC<CalendarProps> = ({
   autoScrollToNow = false,
   cleaningIcon,
 }) => {
+  // Validate props in development mode
+  useEffect(() => {
+    if (process.env.NODE_ENV !== "production") {
+      const errors = validateCalendarProps({
+        events,
+        date,
+        onDateChange,
+        onEventPress,
+        view,
+      });
+      logValidationErrors(errors);
+    }
+  }, [events, date, onDateChange, onEventPress, view]);
+
   // Merge user theme with default theme
   const mergedTheme = mergeTheme(theme);
 
@@ -155,7 +171,7 @@ export const CustomCalendar: React.FC<CalendarProps> = ({
       <View
         key={`month-${viewKey}`} // Force remount on view change
         style={[styles.container, { backgroundColor: mergedTheme.background }]}
-        onLayout={(e) => {
+        onLayout={(e: LayoutChangeEvent) => {
           const newHeight = e.nativeEvent.layout.height;
           if (newHeight > 0) {
             setHeight(newHeight);

package/src/DayView/hooks/useScrollSynchronization.ts

@@ -39,7 +39,7 @@ export const useScrollSynchronization = () => {
    * Runs on UI thread for zero-latency synchronization
    */
   const handleHeaderScroll = useAnimatedScrollHandler({
-    onScroll: (event) => {
+    onScroll: (event: { contentOffset: { x: number; y: number } }) => {
       // Ignore if content is currently being scrolled by user
       if (isContentScrolling.value) {
         return;
@@ -69,7 +69,7 @@ export const useScrollSynchronization = () => {
    * Runs on UI thread for zero-latency synchronization
    */
   const handleContentScroll = useAnimatedScrollHandler({
-    onScroll: (event) => {
+    onScroll: (event: { contentOffset: { x: number; y: number } }) => {
       // Ignore if header is currently being scrolled by user
       if (isHeaderScrolling.value) {
         return;

package/src/DayView/index.tsx

@@ -197,9 +197,7 @@ export const DayView: React.FC<DayViewProps> = ({
     <CalendarErrorBoundary
       theme={theme}
       onError={(error, errorInfo) => {
-        if (process.env.NODE_ENV !== "production") {
-          console.error("DayView Error:", error, errorInfo);
-        }
+        // Error handled by ErrorBoundary's onError callback
       }}
     >
       <View style={[styles.container, { backgroundColor: theme.background }]}>
@@ -238,7 +236,7 @@ export const DayView: React.FC<DayViewProps> = ({
             showsVerticalScrollIndicator={true}
             showsHorizontalScrollIndicator={false}
             onScroll={useAnimatedScrollHandler({
-              onScroll: (event) => {
+              onScroll: (event: { contentOffset: { y: number } }) => {
                 scrollY.value = event.contentOffset.y;
               },
             })}
@@ -310,19 +308,21 @@ const createStyles = (theme: CalendarTheme) =>
     container: {
       flex: 1,
       // Web-specific: Ensure container has constrained height for scrolling
-      ...(Platform.OS === 'web' && typeof window !== 'undefined' && {
-        height: '100%',
-        minHeight: 0, // Important for flex children on web
-      }),
+      ...(Platform.OS === "web" &&
+        typeof window !== "undefined" && {
+          height: "100%",
+          minHeight: 0, // Important for flex children on web
+        }),
     },
     contentContainer: {
       flex: 1,
       backgroundColor: theme.background,
       // Web-specific: Constrain height for scrolling
-      ...(Platform.OS === 'web' && typeof window !== 'undefined' && {
-        height: '100%',
-        minHeight: 0,
-      }),
+      ...(Platform.OS === "web" &&
+        typeof window !== "undefined" && {
+          height: "100%",
+          minHeight: 0,
+        }),
     },
     stickyHeadersContainer: {
       flexDirection: "row",
@@ -336,9 +336,10 @@ const createStyles = (theme: CalendarTheme) =>
     stickyHeadersScroll: {
       flex: 1,
       // Web-specific: Ensure horizontal scrolling works
-      ...(Platform.OS === 'web' && typeof window !== 'undefined' && {
-        minHeight: 0,
-      }),
+      ...(Platform.OS === "web" &&
+        typeof window !== "undefined" && {
+          minHeight: 0,
+        }),
     },
     stickyHeadersRow: {
       flexDirection: "row",
@@ -347,15 +348,16 @@ const createStyles = (theme: CalendarTheme) =>
       flex: 1,
       paddingTop: CONTENT_PADDING_TOP,
       // Web-specific: Explicit height constraint and overflow for scrolling
-      ...(Platform.OS === 'web' && typeof window !== 'undefined' && {
-        height: '100%',
-        maxHeight: '100%',
-        minHeight: 0,
-        // @ts-ignore - web-specific CSS properties
-        overflowY: 'auto',
-        overflowX: 'hidden',
-        WebkitOverflowScrolling: 'touch',
-      }),
+      ...(Platform.OS === "web" &&
+        typeof window !== "undefined" && {
+          height: "100%",
+          maxHeight: "100%",
+          minHeight: 0,
+          // @ts-ignore - web-specific CSS properties
+          overflowY: "auto",
+          overflowX: "hidden",
+          WebkitOverflowScrolling: "touch",
+        }),
     },
     content: {
       flexDirection: "row",
@@ -368,13 +370,14 @@ const createStyles = (theme: CalendarTheme) =>
     propertyLanesScroll: {
       flex: 1,
       // Web-specific: Ensure horizontal scrolling works
-      ...(Platform.OS === 'web' && typeof window !== 'undefined' && {
-        minHeight: 0,
-        // @ts-ignore - web-specific CSS properties
-        overflowX: 'auto',
-        overflowY: 'hidden',
-        WebkitOverflowScrolling: 'touch',
-      }),
+      ...(Platform.OS === "web" &&
+        typeof window !== "undefined" && {
+          minHeight: 0,
+          // @ts-ignore - web-specific CSS properties
+          overflowX: "auto",
+          overflowY: "hidden",
+          WebkitOverflowScrolling: "touch",
+        }),
     },
     propertyLanesRow: {
       flexDirection: "row",

package/src/MonthView/OverflowIndicator.tsx

@@ -32,7 +32,7 @@ export const OverflowIndicator: React.FC<OverflowIndicatorProps> = ({
         // backgroundColor: `${theme.text}10`,
         zIndex: 200,
       }}
-      onPress={(e) => {
+      onPress={(e: any) => {
         e.stopPropagation(); // Prevent day cell click
         onPress();
       }}

package/src/MonthView/index.tsx

@@ -2,6 +2,7 @@ import calendarize from "calendarize";
 import dayjs from "dayjs";
 import * as React from "react";
 import { Text, TouchableOpacity, View, Dimensions } from "react-native";
+import type { LayoutChangeEvent } from "react-native";
 import { CalendarEvent } from "../types";
 import { CalendarTheme } from "../utils/theme";
 import { useSwipeGesture } from "../hooks";
@@ -146,8 +147,8 @@ export const MonthView: React.FC<MonthViewProps> = ({
         // borderColor: theme.border,
         // borderRadius: 4,
       }}
-      onLayout={({ nativeEvent: { layout } }) => {
-        setCalendarWidth(layout.width);
+      onLayout={(e: LayoutChangeEvent) => {
+        setCalendarWidth(e.nativeEvent.layout.width);
       }}
       {...panResponder.panHandlers}
     >

package/src/MonthView/utils.ts

@@ -1,4 +1,5 @@
 import dayjs from "dayjs";
+import type { Dayjs } from "dayjs";
 import isBetween from "dayjs/plugin/isBetween";
 import { CalendarEvent } from "../types";
 import { EventPosition, HorizontalPosition } from "./types";
@@ -16,7 +17,7 @@ dayjs.extend(isBetween);
  */
 export function getHorizontalPositionInDay(
   event: CalendarEvent,
-  date: dayjs.Dayjs,
+  date: Dayjs,
   cellWidth: number
 ): HorizontalPosition {
   const dayStart = date.startOf("day");
@@ -51,7 +52,7 @@ export function getHorizontalPositionInDay(
  */
 export function getMultiDayPosition(
   event: CalendarEvent,
-  weekStartDate: dayjs.Dayjs,
+  weekStartDate: Dayjs,
   weekIndex: number,
   cellWidth: number
 ): EventPosition | null {
@@ -212,7 +213,7 @@ export function assignGlobalRows(
 export function calculateOverflowByDay(
   eventPositions: EventPosition[],
   weeks: number[][],
-  target: dayjs.Dayjs,
+  target: Dayjs,
   maxVisibleRows: number
 ): Map<string, number> {
   const overflowMap = new Map<string, number>();

package/src/WeekView/OverflowIndicator.tsx

@@ -33,13 +33,13 @@ export const WeekOverflowIndicator: React.FC<Props> = ({
 }) => {
   const label = showCount && count > 0 ? `+${count}` : undefined;
   // Use Unicode chevrons instead of icon library for web compatibility
-  const chevronSymbol = chevron === "up" ? "▲" : chevron === "down" ? "▼" : null;
+  const chevronSymbol =
+    chevron === "up" ? "▲" : chevron === "down" ? "▼" : null;
 
   return (
     <TouchableOpacity
       style={[styles.container, style]}
       onPress={() => {
-        console.log("WeekOverflowIndicator pressed");
         onPress && onPress();
       }}
       hitSlop={{ top: 8, bottom: 8, left: 8, right: 8 }}

package/src/WeekView/index.tsx

@@ -73,7 +73,7 @@ export const WeekView: React.FC<WeekViewProps> = ({
 }) => {
   // SSR-safe: useWindowDimensions may not be available during SSR
   const windowDimensions = useWindowDimensions();
-  const width = typeof window !== 'undefined' ? windowDimensions.width : 0;
+  const width = typeof window !== "undefined" ? windowDimensions.width : 0;
   const dayColumnWidth = Math.floor((width - TIME_COLUMN_WIDTH) / 7);
 
   const totalHeight = HOURS_IN_DAY * WEEK_VIEW_HOUR_HEIGHT;
@@ -184,9 +184,7 @@ export const WeekView: React.FC<WeekViewProps> = ({
     <CalendarErrorBoundary
       theme={theme}
       onError={(error, errorInfo) => {
-        if (process.env.NODE_ENV !== "production") {
-          console.error("WeekView Error:", error, errorInfo);
-        }
+        // Error handled by ErrorBoundary's onError callback
       }}
     >
       <View style={styles.container}>
@@ -237,7 +235,7 @@ export const WeekView: React.FC<WeekViewProps> = ({
           showsVerticalScrollIndicator
           showsHorizontalScrollIndicator={false}
           onScroll={useAnimatedScrollHandler({
-            onScroll: (event) => {
+            onScroll: (event: { contentOffset: { y: number } }) => {
               scrollY.value = event.contentOffset.y;
             },
           })}
@@ -339,10 +337,11 @@ const createStyles = (theme: CalendarTheme, totalHeight: number) =>
       backgroundColor: theme.background,
       position: "relative",
       // Web-specific: Ensure container has constrained height for scrolling
-      ...(Platform.OS === 'web' && typeof window !== 'undefined' && {
-        height: '100%',
-        minHeight: 0, // Important for flex children on web
-      }),
+      ...(Platform.OS === "web" &&
+        typeof window !== "undefined" && {
+          height: "100%",
+          minHeight: 0, // Important for flex children on web
+        }),
     },
     todayHighlight: {
       position: "absolute",
@@ -367,15 +366,16 @@ const createStyles = (theme: CalendarTheme, totalHeight: number) =>
       flex: 1,
       paddingTop: DAY_OVERFLOW_TOP_INSET,
       // Web-specific: Explicit height constraint and overflow for scrolling
-      ...(Platform.OS === 'web' && typeof window !== 'undefined' && {
-        height: '100%',
-        maxHeight: '100%',
-        minHeight: 0,
-        // @ts-ignore - web-specific CSS properties
-        overflowY: 'auto',
-        overflowX: 'hidden',
-        WebkitOverflowScrolling: 'touch',
-      }),
+      ...(Platform.OS === "web" &&
+        typeof window !== "undefined" && {
+          height: "100%",
+          maxHeight: "100%",
+          minHeight: 0,
+          // @ts-ignore - web-specific CSS properties
+          overflowY: "auto",
+          overflowX: "hidden",
+          WebkitOverflowScrolling: "touch",
+        }),
     },
     content: {
       flexDirection: "row",

package/src/hooks/useSwipeGesture.ts

@@ -1,5 +1,5 @@
 import { useRef, useMemo } from "react";
-import { PanResponder, PanResponderInstance, Platform } from "react-native";
+import { PanResponder, PanResponderInstance, PanResponderGestureState, Platform } from "react-native";
 
 /**
  * Configuration options for swipe gesture detection
@@ -76,7 +76,7 @@ export function useSwipeGesture(
        * Only respond to horizontal gestures (where horizontal movement > vertical movement).
        * See: https://stackoverflow.com/questions/47568850/touchableopacity-with-parent-panresponder
        */
-      onMoveShouldSetPanResponder: (_, gestureState) => {
+      onMoveShouldSetPanResponder: (_: any, gestureState: PanResponderGestureState) => {
         if (!enabled) {
           return false;
         }
@@ -97,7 +97,7 @@ export function useSwipeGesture(
        * Handle the gesture movement.
        * Trigger callbacks when threshold is exceeded.
        */
-      onPanResponderMove: (_, gestureState) => {
+      onPanResponderMove: (_: any, gestureState: PanResponderGestureState) => {
         const { dx, dy } = gestureState;
 
         // Ignore if:

package/src/shared/ErrorBoundary.tsx

@@ -38,9 +38,6 @@ export class CalendarErrorBoundary extends Component<
   }
 
   componentDidCatch(error: Error, errorInfo: React.ErrorInfo): void {
-    if (process.env.NODE_ENV !== "production") {
-      console.error("Calendar Error:", error, errorInfo);
-    }
     this.props.onError?.(error, errorInfo);
   }
 

package/src/types/dayjs.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Type declarations for dayjs
+ * dayjs is a peer dependency, so types are provided here for type checking
+ */
+declare module 'dayjs' {
+  export interface Dayjs {
+    format(template?: string): string;
+    startOf(unit: 'day' | 'month' | 'year' | 'hour' | 'minute' | 'second' | 'week'): Dayjs;
+    endOf(unit: 'day' | 'month' | 'year' | 'hour' | 'minute' | 'second' | 'week'): Dayjs;
+    add(value: number, unit: 'day' | 'month' | 'year' | 'hour' | 'minute' | 'second' | 'week'): Dayjs;
+    subtract(value: number, unit: 'day' | 'month' | 'year' | 'hour' | 'minute' | 'second' | 'week'): Dayjs;
+    toDate(): Date;
+    valueOf(): number;
+    [key: string]: any;
+  }
+
+  interface DayjsExtend {
+    extend(plugin: any, option?: any): void;
+  }
+
+  const dayjs: ((date?: Date | string | number) => Dayjs) & DayjsExtend;
+  
+  export default dayjs;
+}
+

package/src/types/react-native.d.ts

@@ -26,8 +26,30 @@ declare module 'react-native' {
   export const PanResponder: any;
   
   export type PanResponderInstance = any;
+  export type PanResponderGestureState = {
+    dx: number;
+    dy: number;
+    moveX: number;
+    moveY: number;
+    numberActiveTouches: number;
+    stateID: number;
+    vx: number;
+    vy: number;
+    x0: number;
+    y0: number;
+  };
   export type NativeSyntheticEvent<T> = any;
   export type NativeTouchEvent = any;
   export type StyleProp<T> = any;
+  export type LayoutChangeEvent = {
+    nativeEvent: {
+      layout: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+      };
+    };
+  };
 }
 

package/src/utils/index.ts

@@ -20,6 +20,9 @@ export * from "./eventHelpers";
 // Property colors
 export * from "./propertyColors";
 
+// Validation utilities
+export * from "./validation";
+
 // Platform detection utilities
 export * from "./platform";
 

package/src/utils/validation.ts

@@ -0,0 +1,203 @@
+/**
+ * Prop validation utilities for Calendar component
+ * Provides helpful error messages for common mistakes
+ */
+
+import { CalendarEvent, ViewMode } from "../types";
+
+export interface ValidationError {
+  field: string;
+  message: string;
+  index?: number;
+}
+
+/**
+ * Validate a CalendarEvent object
+ * @param event - The event to validate
+ * @param index - Index of the event in the array (for error messages)
+ * @returns Array of validation errors (empty if valid)
+ */
+export function validateEvent(
+  event: CalendarEvent,
+  index: number
+): ValidationError[] {
+  const errors: ValidationError[] = [];
+
+  // Check required fields
+  if (!event.id || typeof event.id !== "string") {
+    errors.push({
+      field: "id",
+      message: `Event at index ${index}: "id" is required and must be a string`,
+      index,
+    });
+  }
+
+  if (!event.eventId || typeof event.eventId !== "string") {
+    errors.push({
+      field: "eventId",
+      message: `Event at index ${index}: "eventId" is required and must be a string`,
+      index,
+    });
+  }
+
+  if (!event.title || typeof event.title !== "string") {
+    errors.push({
+      field: "title",
+      message: `Event at index ${index}: "title" is required and must be a string`,
+      index,
+    });
+  }
+
+  // Check start date
+  if (!event.start) {
+    errors.push({
+      field: "start",
+      message: `Event at index ${index}: "start" is required`,
+      index,
+    });
+  } else if (!(event.start instanceof Date)) {
+    errors.push({
+      field: "start",
+      message: `Event at index ${index}: "start" must be a Date object, got ${typeof event.start}. Use: new Date(dateString) to convert.`,
+      index,
+    });
+  } else if (isNaN(event.start.getTime())) {
+    errors.push({
+      field: "start",
+      message: `Event at index ${index}: "start" is an invalid Date`,
+      index,
+    });
+  }
+
+  // Check end date
+  if (!event.end) {
+    errors.push({
+      field: "end",
+      message: `Event at index ${index}: "end" is required`,
+      index,
+    });
+  } else if (!(event.end instanceof Date)) {
+    errors.push({
+      field: "end",
+      message: `Event at index ${index}: "end" must be a Date object, got ${typeof event.end}. Use: new Date(dateString) to convert.`,
+      index,
+    });
+  } else if (isNaN(event.end.getTime())) {
+    errors.push({
+      field: "end",
+      message: `Event at index ${index}: "end" is an invalid Date`,
+      index,
+    });
+  }
+
+  // Check date range validity
+  if (
+    event.start instanceof Date &&
+    event.end instanceof Date &&
+    !isNaN(event.start.getTime()) &&
+    !isNaN(event.end.getTime())
+  ) {
+    if (event.start >= event.end) {
+      errors.push({
+        field: "dateRange",
+        message: `Event at index ${index}: "start" date must be before "end" date`,
+        index,
+      });
+    }
+  }
+
+  return errors;
+}
+
+/**
+ * Validate Calendar component props
+ * @param props - The props to validate
+ * @returns Array of validation errors (empty if valid)
+ */
+export function validateCalendarProps(props: {
+  events: CalendarEvent[];
+  date: Date;
+  onDateChange?: (date: Date) => void;
+  onEventPress?: (event: CalendarEvent) => void;
+  view?: ViewMode;
+}): ValidationError[] {
+  const errors: ValidationError[] = [];
+
+  // Validate date prop
+  if (!props.date) {
+    errors.push({
+      field: "date",
+      message: '"date" prop is required',
+    });
+  } else if (!(props.date instanceof Date)) {
+    errors.push({
+      field: "date",
+      message: `"date" must be a Date object, got ${typeof props.date}. Use: new Date() or new Date(dateString)`,
+    });
+  } else if (isNaN(props.date.getTime())) {
+    errors.push({
+      field: "date",
+      message: '"date" is an invalid Date',
+    });
+  }
+
+  // Validate required callbacks
+  if (!props.onDateChange || typeof props.onDateChange !== "function") {
+    errors.push({
+      field: "onDateChange",
+      message: '"onDateChange" prop is required and must be a function',
+    });
+  }
+
+  if (!props.onEventPress || typeof props.onEventPress !== "function") {
+    errors.push({
+      field: "onEventPress",
+      message: '"onEventPress" prop is required and must be a function',
+    });
+  }
+
+  // Validate view prop
+  if (props.view && !["month", "week", "day"].includes(props.view)) {
+    errors.push({
+      field: "view",
+      message: `"view" must be one of: "month", "week", "day". Got: ${props.view}`,
+    });
+  }
+
+  // Validate events array
+  if (!Array.isArray(props.events)) {
+    errors.push({
+      field: "events",
+      message: '"events" must be an array',
+    });
+  } else {
+    // Validate each event
+    props.events.forEach((event, index) => {
+      const eventErrors = validateEvent(event, index);
+      errors.push(...eventErrors);
+    });
+  }
+
+  return errors;
+}
+
+/**
+ * Log validation errors in development mode
+ * @param errors - Array of validation errors
+ */
+export function logValidationErrors(errors: ValidationError[]): void {
+  if (errors.length === 0) return;
+
+  if (process.env.NODE_ENV !== "production") {
+    console.error(
+      "❌ Calendar Component Validation Errors:\n" +
+        errors.map((err) => `  • ${err.message}`).join("\n") +
+        "\n\n" +
+        "Common fixes:\n" +
+        "  • Convert date strings to Date objects: new Date(dateString)\n" +
+        "  • Ensure start < end for all events\n" +
+        "  • Provide required callbacks: onDateChange, onEventPress"
+    );
+  }
+}
+

package/tsup.config.ts

@@ -1,7 +1,7 @@
 import { defineConfig } from "tsup";
 
 export default defineConfig({
-  entry: ["index.ts"],
+  entry: ["src/index.ts"],
   format: ["cjs", "esm"],
   dts: true,
   sourcemap: true,