@mui-toolpad-extended-tuni/calendar 3.0.1 → 3.1.0

package/README.md

@@ -5,29 +5,64 @@ Calendar microservice extension for MUI Toolpad Extended TUNI. This package prov
 ## Installation
 
 ```bash
-npm install @mui-toolpad-extended-tuni/calendar
+npm install @mui-toolpad-extended-tuni/calendar @mui-toolpad-extended-tuni/main @mui-toolpad-extended-tuni/core
 ```
 
-**Note**: This package requires `mui-toolpad-extended-tuni@^3.0.0` as a peer dependency.
+**Important**: You must also install `@mui-toolpad-extended-tuni/main` and `@mui-toolpad-extended-tuni/core` as they are required peer dependencies.
 
-## Peer Dependencies
+## Required Peer Dependencies
 
-- `mui-toolpad-extended-tuni@^3.0.0`
+This package requires the following peer dependencies to be installed:
+
+### Required Packages
+- **`@mui-toolpad-extended-tuni/main`**: ^3.4.0 - **MUST be installed separately**
+- **`@mui-toolpad-extended-tuni/core`**: ^3.2.0 - **MUST be installed separately** (also required by main)
+
+### React & UI Framework
 - `react@^19.0.0`
 - `react-dom@^19.0.0`
 - `react-router-dom@^7.0.0`
 - `@mui/material@^7.0.0`
 - `@mui/icons-material@^7.0.0`
 - `@mui/x-date-pickers@^7.0.0`
+- `@emotion/react@^11.0.0`
+- `@emotion/styled@^11.0.0`
+
+### Calendar Dependencies
 - `@fullcalendar/core@^6.0.0`
 - `@fullcalendar/daygrid@^6.0.0`
 - `@fullcalendar/interaction@^6.0.0`
 - `@fullcalendar/react@^6.0.0`
 - `@fullcalendar/timegrid@^6.0.0`
-- `@emotion/react@^11.0.0`
-- `@emotion/styled@^11.0.0`
 - `luxon@^3.0.0`
 
+### Installation Example
+
+```bash
+npm install @mui-toolpad-extended-tuni/calendar @mui-toolpad-extended-tuni/main @mui-toolpad-extended-tuni/core \
+  react react-dom react-router-dom \
+  @mui/material @mui/icons-material @mui/x-date-pickers \
+  @emotion/react @emotion/styled \
+  @fullcalendar/core @fullcalendar/daygrid @fullcalendar/interaction @fullcalendar/react @fullcalendar/timegrid \
+  luxon
+```
+
+## API Configuration
+
+**Note**: The calendar package does not make direct API calls. It receives events through the EventBus system from other microservices (primarily the courses package). However, you can configure calendar endpoints if you plan to add direct API integration in the future.
+
+### Default Endpoints
+
+If you need to configure calendar endpoints for future API integration:
+
+- `get: "api/calendar/"` - GET list of calendar events
+- `getById: "api/calendar/:id"` - GET event by ID
+- `post: "api/calendar/"` - POST create new event
+- `put: "api/calendar/:id/"` - PUT update event
+- `delete: "api/calendar/:id/"` - DELETE event
+
+**Current Implementation**: The calendar currently uses EventBus to receive events from other microservices. Direct API endpoints are reserved for future use.
+
 ## Usage
 
 ### Basic Setup
@@ -194,6 +229,71 @@ Events from courses are automatically color-coded:
 - **By Level**: Basic (light), Intermediate (medium), Advanced (dark) shades
 - **By Type**: Different event types (lecture, exercise, exam, etc.) have distinct styling
 
+## Data Types
+
+### CalendarEvent
+
+Calendar event object displayed in the calendar.
+
+```typescript
+interface CalendarEvent {
+  id: string;                      // Unique event ID
+  title: string;                   // Event title
+  start: Date | string;            // Event start date/time (ISO string or Date)
+  end?: Date | string;             // Event end date/time (optional)
+  backgroundColor?: string;        // Background color (hex)
+  borderColor?: string;            // Border color (hex)
+  textColor?: string;             // Text color (hex)
+  extendedProps?: {                // Additional event metadata
+    courseCode?: string;           // Course code (if from courses package)
+    courseTitle?: string;          // Course title
+    type?: string;                 // Event type
+    description?: string;          // Event description
+    location?: string;             // Event location
+    [key: string]: any;            // Additional custom properties
+  };
+}
+```
+
+### CalendarEventType
+
+Type of calendar event.
+
+```typescript
+type CalendarEventType = 
+  | "lecture"      // Lecture events
+  | "exercise"     // Exercise sessions
+  | "exam"         // Examinations
+  | "deadline"     // Assignment deadlines
+  | "other"        // Other events
+  | "meeting"      // Meetings
+  | "maintenance"; // Maintenance windows
+```
+
+### EventBus Event Format
+
+Events received from EventBus (e.g., from courses package) follow this structure:
+
+```typescript
+interface Event {
+  id: string;
+  title: string;
+  start: string;                   // ISO date string
+  end: string;                      // ISO date string
+  metadata: {
+    source: string;                 // Event source (e.g., "courses")
+    type?: CalendarEventType;       // Event type
+    courseCode?: string;            // Course code
+    courseTitle?: string;           // Course title
+    subject?: string;               // Course subject
+    courseLevel?: "basic" | "intermediate" | "advanced";
+    description?: string;
+    location?: string;
+    [key: string]: any;             // Additional metadata
+  };
+}
+```
+
 ## Exports
 
 ### Components
@@ -205,9 +305,13 @@ Events from courses are automatically color-coded:
 
 ### Store
 - `useCalendarStore` - Zustand store for calendar management
+- `createCalendarEvent` - Helper function to create calendar events
+- `getContrastColor` - Helper function to get contrasting text color
 
 ### Types
-- `CalendarEventType` - Calendar event type (lecture, exercise, exam, deadline, other, meeting, maintenance)
+- `CalendarEvent` - Calendar event interface
+- `CalendarEventType` - Calendar event type enumeration
+- `CalendarApiEndpoints` - API endpoint configuration type (for future use)
 
 ## Features