cleanhaus-calendar 1.0.0 → 1.0.2

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
-
-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
+**Note:** Production builds automatically use webpack, so no additional configuration is needed for deployment.
 
-### 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,76 @@ 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
+- **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**: Prevents hydration errors automatically
 
-## 🐛 Troubleshooting
+## Troubleshooting
 
-### Events not appearing
-- ✅ Ensure `start` and `end` are `Date` objects (not strings)
-- ✅ Check `eventId` is set correctly
-- ✅ Verify `containerHeight` is sufficient (minimum 400px)
+**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
 
-### Next.js Issues
+**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
 
-**Module not found:**
-- ✅ Restart dev server: `npm run dev -- --webpack`
-- ✅ Clear cache: `rm -rf .next`
+- 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)