@umituz/react-native-design-system 2.3.13 → 2.3.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@umituz/react-native-design-system",
-  "version": "2.3.13",
+  "version": "2.3.14",
   "description": "Universal design system for React Native apps - Consolidated package with atoms, molecules, organisms, theme, typography, responsive and safe area utilities",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -54,6 +54,11 @@
     "@react-native-async-storage/async-storage": ">=2.0.0",
     "@react-native-community/datetimepicker": ">=8.0.0",
     "@react-navigation/native": ">=6.0.0",
+    "@umituz/react-native-uuid": "latest",
+    "expo-application": ">=5.0.0",
+    "expo-calendar": ">=13.0.0",
+    "expo-crypto": ">=13.0.0",
+    "expo-device": ">=5.0.0",
     "expo-linear-gradient": ">=15.0.0",
     "react": ">=19.0.0",
     "react-native": ">=0.81.0",
@@ -61,11 +66,7 @@
     "react-native-reanimated": ">=3.16.0",
     "react-native-safe-area-context": ">=5.0.0",
     "react-native-svg": ">=15.0.0",
-    "zustand": ">=5.0.0",
-    "expo-device": ">=5.0.0",
-    "expo-application": ">=5.0.0",
-    "@umituz/react-native-uuid": "latest",
-    "expo-crypto": ">=13.0.0"
+    "zustand": ">=5.0.0"
   },
   "peerDependenciesMeta": {
     "expo-linear-gradient": {
@@ -95,10 +96,16 @@
     "@types/react": "~19.1.10",
     "@typescript-eslint/eslint-plugin": "^8.50.1",
     "@typescript-eslint/parser": "^8.50.1",
+    "@umituz/react-native-uuid": "latest",
     "eslint": "^9.39.2",
     "eslint-plugin-react": "^7.37.5",
     "eslint-plugin-react-hooks": "^7.0.1",
     "eslint-plugin-react-native": "^5.0.0",
+    "expo-application": "~5.9.1",
+    "expo-calendar": "~14.0.0",
+    "expo-crypto": "~14.0.0",
+    "expo-device": "~7.0.2",
+    "expo-localization": "~16.0.1",
     "react": "19.1.0",
     "react-native": "0.81.5",
     "react-native-gesture-handler": "^2.20.0",
@@ -106,12 +113,7 @@
     "react-native-safe-area-context": "^5.6.0",
     "react-native-svg": "15.12.1",
     "typescript": "~5.9.2",
-    "zustand": "^5.0.2",
-    "expo-device": "~7.0.2",
-    "expo-application": "~5.9.1",
-    "expo-localization": "~16.0.1",
-    "@umituz/react-native-uuid": "latest",
-    "expo-crypto": "~14.0.0"
+    "zustand": "^5.0.2"
   },
   "publishConfig": {
     "access": "public"

package/src/index.ts

@@ -301,6 +301,31 @@ export {
   type Alert,
   type AlertAction,
   type AlertOptions,
+  // Calendar
+  AtomicCalendar,
+  useCalendar,
+  useCalendarNavigation,
+  useCalendarEvents,
+  useSystemCalendar,
+  CalendarService,
+  CalendarPermissions,
+  CalendarEvents,
+  CalendarGeneration,
+  CalendarSync,
+  DateUtilities,
+  useCalendarStore,
+  type AtomicCalendarProps,
+  type UseCalendarReturn,
+  type CalendarEvent,
+  type CreateCalendarEventRequest,
+  type UpdateCalendarEventRequest,
+  type SystemCalendar,
+  type CalendarPermissionResult,
+  type CalendarDay,
+  type CalendarMonth,
+  type CalendarWeek,
+  type ICalendarRepository,
+  type CalendarViewMode,
 } from './molecules';
 
 // =============================================================================

package/src/molecules/calendar/domain/entities/CalendarDay.entity.ts

@@ -0,0 +1,115 @@
+/**
+ * CalendarDay Entity
+ *
+ * Represents a single day in a calendar view with its properties and associated events.
+ *
+ * Design Philosophy:
+ * - Timezone-aware (uses timezone domain for date calculations)
+ * - Event-agnostic (works with any CalendarEvent type)
+ * - View-ready (contains all display state)
+ * - Immutable (never mutate, create new instances)
+ */
+
+import type { CalendarEvent } from './CalendarEvent.entity';
+
+export interface CalendarDay {
+  /**
+   * The date this calendar day represents
+   */
+  date: Date;
+
+  /**
+   * Whether this day belongs to the currently displayed month
+   * Used to gray out days from prev/next months in calendar grid
+   */
+  isCurrentMonth: boolean;
+
+  /**
+   * Whether this day is today (timezone-aware via timezone domain)
+   */
+  isToday: boolean;
+
+  /**
+   * Whether this day is currently selected by the user
+   */
+  isSelected: boolean;
+
+  /**
+   * Events scheduled for this day
+   * @default []
+   */
+  events: CalendarEvent[];
+
+  /**
+   * Whether this day is disabled/non-selectable
+   * @example Past dates, dates outside valid range
+   * @default false
+   */
+  isDisabled?: boolean;
+
+  /**
+   * Whether this day is a weekend (Saturday or Sunday)
+   * Useful for styling weekend days differently
+   */
+  isWeekend?: boolean;
+}
+
+/**
+ * Calendar Month Configuration
+ *
+ * Represents a full month view with all necessary display information
+ */
+export interface CalendarMonth {
+  /**
+   * Year of the month
+   */
+  year: number;
+
+  /**
+   * Month (0-indexed: 0 = January, 11 = December)
+   */
+  month: number;
+
+  /**
+   * All days to display in the calendar grid (usually 42 days = 6 weeks)
+   * Includes days from previous and next months to fill the grid
+   */
+  days: CalendarDay[];
+
+  /**
+   * First day of the month
+   */
+  firstDay: Date;
+
+  /**
+   * Last day of the month
+   */
+  lastDay: Date;
+
+  /**
+   * Total number of days in this month
+   */
+  daysInMonth: number;
+}
+
+/**
+ * Week View Configuration
+ *
+ * Represents a week view with 7 days
+ */
+export interface CalendarWeek {
+  /**
+   * Start date of the week (usually Sunday)
+   */
+  startDate: Date;
+
+  /**
+   * End date of the week (usually Saturday)
+   */
+  endDate: Date;
+
+  /**
+   * All 7 days in the week
+   */
+  days: CalendarDay[];
+}

package/src/molecules/calendar/domain/entities/CalendarEvent.entity.ts

@@ -0,0 +1,202 @@
+/**
+ * CalendarEvent Entity
+ *
+ * Generic calendar event that can represent:
+ * - Workouts (fitness apps)
+ * - Habits (habit tracking apps)
+ * - Tasks (productivity apps)
+ * - Appointments (scheduling apps)
+ * - Any other time-based event
+ *
+ * Design Philosophy:
+ * - Generic and reusable across all app types
+ * - Extensible via metadata field
+ * - Simple core properties
+ * - App-specific data in metadata
+ */
+
+export interface CalendarEvent {
+  /**
+   * Unique identifier for the event
+   */
+  id: string;
+
+  /**
+   * Event title/name
+   * @example "Morning Workout", "Team Meeting", "Water plants"
+   */
+  title: string;
+
+  /**
+   * Event date in YYYY-MM-DD format (timezone-aware via timezone domain)
+   * @example "2024-10-30"
+   */
+  date: string;
+
+  /**
+   * Optional event time in HH:mm format
+   * @example "09:30", "14:00"
+   */
+  time?: string;
+
+  /**
+   * Optional event color for visual distinction
+   * Uses design token color names or hex values
+   * @example "primary", "success", "#FF5733"
+   */
+  color?: string;
+
+  /**
+   * Whether the event has been completed/checked off
+   * @default false
+   */
+  isCompleted?: boolean;
+
+  /**
+   * Optional duration in minutes
+   * @example 30, 60, 90
+   */
+  duration?: number;
+
+  /**
+   * Optional event description/notes
+   */
+  description?: string;
+
+  /**
+   * Optional location for the event
+   */
+  location?: string;
+
+  /**
+   * Reminders/alarms (minutes before event)
+   * @example [15, 30] → 15 mins and 30 mins before
+   */
+  reminders?: number[];
+
+  /**
+   * System calendar sync (expo-calendar integration)
+   */
+  systemCalendar?: {
+    /**
+     * System calendar ID where event is synced
+     */
+    calendarId: string;
+
+    /**
+     * System event ID from device calendar
+     */
+    eventId: string;
+
+    /**
+     * Last sync timestamp
+     */
+    lastSyncedAt: Date;
+  };
+
+  /**
+   * App-specific metadata
+   * Use this for domain-specific properties
+   * @example
+   * // Workout app:
+   * metadata: { workoutTemplateId: "abc123", exercises: [...] }
+   *
+   * // Habit app:
+   * metadata: { habitId: "xyz789", streak: 5 }
+   */
+  metadata?: unknown;
+
+  /**
+   * Recurring event configuration
+   */
+  recurring?: {
+    /**
+     * Recurrence pattern
+     */
+    pattern: 'daily' | 'weekly' | 'monthly' | 'custom';
+
+    /**
+     * Interval for recurrence
+     * @example pattern: 'weekly', interval: 2 → every 2 weeks
+     */
+    interval?: number;
+
+    /**
+     * Days of week for weekly recurrence (0 = Sunday, 6 = Saturday)
+     * @example [1, 3, 5] → Monday, Wednesday, Friday
+     */
+    daysOfWeek?: number[];
+
+    /**
+     * End date for recurrence (YYYY-MM-DD)
+     */
+    endDate?: string;
+  };
+
+  /**
+   * Creation timestamp
+   */
+  createdAt: Date;
+
+  /**
+   * Last update timestamp
+   */
+  updatedAt: Date;
+}
+
+/**
+ * Request object for creating a new calendar event
+ */
+export interface CreateCalendarEventRequest {
+  title: string;
+  date: string;
+  time?: string;
+  color?: string;
+  duration?: number;
+  description?: string;
+  location?: string;
+  reminders?: number[];
+  metadata?: unknown;
+  recurring?: CalendarEvent['recurring'];
+  syncToSystemCalendar?: boolean; // Auto-sync to device calendar
+}
+
+/**
+ * Request object for updating an existing calendar event
+ */
+export interface UpdateCalendarEventRequest {
+  id: string;
+  title?: string;
+  date?: string;
+  time?: string;
+  color?: string;
+  isCompleted?: boolean;
+  duration?: number;
+  description?: string;
+  location?: string;
+  reminders?: number[];
+  metadata?: unknown;
+  recurring?: CalendarEvent['recurring'];
+  systemCalendar?: CalendarEvent['systemCalendar'];
+}
+
+/**
+ * System calendar list item
+ */
+export interface SystemCalendar {
+  id: string;
+  title: string;
+  color: string;
+  source: string;
+  isPrimary: boolean;
+  allowsModifications: boolean;
+}
+
+/**
+ * Calendar permission result
+ */
+export interface CalendarPermissionResult {
+  granted: boolean;
+  canAskAgain: boolean;
+  status: string;
+}

package/src/molecules/calendar/domain/repositories/ICalendarRepository.ts

@@ -0,0 +1,120 @@
+/**
+ * ICalendarRepository Interface
+ *
+ * Port (interface) for calendar data access operations.
+ * Implementations can use any storage mechanism (AsyncStorage, SQLite, etc.)
+ *
+ * Design Philosophy:
+ * - Repository pattern (DDD)
+ * - Storage-agnostic
+ * - CRUD operations for calendar events
+ * - Query methods for finding events
+ */
+
+import type {
+  CalendarEvent,
+  CreateCalendarEventRequest,
+  UpdateCalendarEventRequest,
+} from '../entities/CalendarEvent.entity';
+
+export interface ICalendarRepository {
+  /**
+   * Get all calendar events
+   * @returns Promise resolving to array of all events
+   */
+  getAllEvents(): Promise<CalendarEvent[]>;
+
+  /**
+   * Get a calendar event by ID
+   * @param id - Event ID
+   * @returns Promise resolving to event or null if not found
+   */
+  getEventById(id: string): Promise<CalendarEvent | null>;
+
+  /**
+   * Get events for a specific date
+   * @param date - Date string in YYYY-MM-DD format
+   * @returns Promise resolving to array of events for that date
+   */
+  getEventsByDate(date: string): Promise<CalendarEvent[]>;
+
+  /**
+   * Get events within a date range
+   * @param startDate - Start date (YYYY-MM-DD)
+   * @param endDate - End date (YYYY-MM-DD)
+   * @returns Promise resolving to array of events in range
+   */
+  getEventsByDateRange(startDate: string, endDate: string): Promise<CalendarEvent[]>;
+
+  /**
+   * Get events for a specific month
+   * @param year - Year (e.g., 2024)
+   * @param month - Month (0-indexed: 0 = January, 11 = December)
+   * @returns Promise resolving to array of events in that month
+   */
+  getEventsByMonth(year: number, month: number): Promise<CalendarEvent[]>;
+
+  /**
+   * Create a new calendar event
+   * @param request - Event creation data
+   * @returns Promise resolving to created event
+   */
+  createEvent(request: CreateCalendarEventRequest): Promise<CalendarEvent>;
+
+  /**
+   * Update an existing calendar event
+   * @param request - Event update data (must include id)
+   * @returns Promise resolving to updated event
+   */
+  updateEvent(request: UpdateCalendarEventRequest): Promise<CalendarEvent>;
+
+  /**
+   * Delete a calendar event
+   * @param id - Event ID to delete
+   * @returns Promise resolving to void
+   */
+  deleteEvent(id: string): Promise<void>;
+
+  /**
+   * Delete all events for a specific date
+   * @param date - Date string in YYYY-MM-DD format
+   * @returns Promise resolving to number of deleted events
+   */
+  deleteEventsByDate(date: string): Promise<number>;
+
+  /**
+   * Mark an event as completed
+   * @param id - Event ID
+   * @returns Promise resolving to updated event
+   */
+  completeEvent(id: string): Promise<CalendarEvent>;
+
+  /**
+   * Mark an event as incomplete
+   * @param id - Event ID
+   * @returns Promise resolving to updated event
+   */
+  uncompleteEvent(id: string): Promise<CalendarEvent>;
+
+  /**
+   * Search events by title
+   * @param query - Search query string
+   * @returns Promise resolving to array of matching events
+   */
+  searchEvents(query: string): Promise<CalendarEvent[]>;
+
+  /**
+   * Get upcoming events (from today onwards)
+   * @param limit - Maximum number of events to return
+   * @returns Promise resolving to array of upcoming events
+   */
+  getUpcomingEvents(limit?: number): Promise<CalendarEvent[]>;
+
+  /**
+   * Get completed events count for a date range
+   * @param startDate - Start date (YYYY-MM-DD)
+   * @param endDate - End date (YYYY-MM-DD)
+   * @returns Promise resolving to count of completed events
+   */
+  getCompletedEventsCount(startDate: string, endDate: string): Promise<number>;
+}

package/src/molecules/calendar/index.ts

@@ -0,0 +1,98 @@
+/**
+ * Calendar Domain - Barrel Export
+ *
+ * Public API for the calendar domain.
+ * Provides generic, reusable calendar functionality for all factory-generated apps.
+ *
+ * Features:
+ * - Timezone-aware calendar generation (built-in DateUtilities)
+ * - Generic event system (workouts, habits, tasks, etc.)
+ * - Month/Week/Day views
+ * - Event CRUD operations with persistence
+ * - Completion tracking
+ * - Recurring events support
+ * - **NEW:** System calendar sync (expo-calendar) - iOS/Android only
+ *
+ * Usage:
+ * ```tsx
+ * import { useCalendar, AtomicCalendar, useSystemCalendar } from '@umituz/react-native-calendar';
+ *
+ * const MyScreen = () => {
+ *   const { days, selectedDate, actions } = useCalendar();
+ *   const {
+ *     systemCalendars,
+ *     permission,
+ *     requestPermission,
+ *     syncEventToCalendar,
+ *   } = useSystemCalendar();
+ *
+ *   // Request permission to access device calendar
+ *   useEffect(() => {
+ *     requestPermission();
+ *   }, []);
+ *
+ *   // Sync event to device calendar
+ *   const handleCreateEvent = async (eventData) => {
+ *     const event = await actions.addEvent(eventData);
+ *     await syncEventToCalendar(event); // Sync to iOS/Android calendar
+ *   };
+ *
+ *   return (
+ *     <AtomicCalendar
+ *       days={days}
+ *       selectedDate={selectedDate}
+ *       onDateSelect={actions.setSelectedDate}
+ *     />
+ *   );
+ * };
+ * ```
+ */
+
+// Domain Entities
+export type {
+  CalendarEvent,
+  CreateCalendarEventRequest,
+  UpdateCalendarEventRequest,
+  SystemCalendar,
+  CalendarPermissionResult,
+} from './domain/entities/CalendarEvent.entity';
+
+export type {
+  CalendarDay,
+  CalendarMonth,
+  CalendarWeek,
+} from './domain/entities/CalendarDay.entity';
+
+// Domain Repositories
+export type { ICalendarRepository } from './domain/repositories/ICalendarRepository';
+
+// Infrastructure Services
+export { CalendarService } from './infrastructure/services/CalendarService';
+export { CalendarPermissions } from './infrastructure/services/CalendarPermissions';
+export { CalendarEvents } from './infrastructure/services/CalendarEvents';
+export { CalendarGeneration } from './infrastructure/services/CalendarGeneration';
+export { CalendarSync } from './infrastructure/services/CalendarSync';
+
+// Infrastructure Utils
+export { DateUtilities } from './infrastructure/utils/DateUtilities';
+
+// Infrastructure Storage
+export {
+  useCalendarStore,
+  type CalendarViewMode,
+} from './infrastructure/storage/CalendarStore';
+
+// Presentation Hooks
+export {
+  useCalendar,
+  useCalendarNavigation,
+  useCalendarEvents,
+  useSystemCalendar,
+  type UseCalendarReturn,
+} from './presentation/hooks/useCalendar';
+
+// Presentation Components
+export {
+  AtomicCalendar,
+  type AtomicCalendarProps,
+} from './presentation/components/AtomicCalendar';