@campxdev/react-blueprint 2.2.3 → 2.2.5

package/src/components/Navigation/Calendar/README.md

@@ -0,0 +1,308 @@
+# Calendar Component
+
+A comprehensive calendar component built on FullCalendar with full MUI theme integration. Supports multiple views, event management, and responsive design.
+
+## Features
+
+- 📅 **Multiple Views**: Month, Week, Day, and List views
+- 🎨 **Theme Integration**: Full MUI theme support with light/dark modes
+- 📱 **Responsive Design**: Mobile-friendly with adaptive layouts
+- ✏️ **Event Management**: Create, edit, delete, and drag-drop events
+- 🎯 **Event Handlers**: Comprehensive callback system for interactions
+- 🔧 **Customizable**: Custom event rendering and styling options
+- ♿ **Accessible**: ARIA compliant and keyboard navigation
+- 🌐 **Internationalization**: Support for multiple locales
+- 📊 **Business Hours**: Constrain events to business hours
+- 🎨 **Custom Styling**: Override default FullCalendar styles
+
+## Installation
+
+The Calendar component comes with the react-blueprint library. Ensure you have the required peer dependencies:
+
+```bash
+yarn add @campxdev/react-blueprint
+```
+
+## Basic Usage
+
+```tsx
+import { Calendar } from '@campxdev/react-blueprint';
+
+const MyCalendar = () => {
+  const events = [
+    {
+      id: '1',
+      title: 'Team Meeting',
+      start: '2024-01-15T09:00:00',
+      end: '2024-01-15T10:00:00',
+    },
+  ];
+
+  return <Calendar events={events} height="600px" initialView="dayGridMonth" />;
+};
+```
+
+## Props
+
+### Event Data
+
+- `events?: CalendarEvent[]` - Array of events to display
+
+### Event Handlers
+
+- `onEventClick?: (eventInfo) => void` - Called when an event is clicked
+- `onEventDrop?: (eventInfo) => void` - Called when an event is dragged and dropped
+- `onEventResize?: (eventInfo) => void` - Called when an event is resized
+- `onDateClick?: (dateInfo) => void` - Called when a date is clicked
+- `onDateSelect?: (selectInfo) => void` - Called when a date range is selected
+- `onEventsSet?: (events) => void` - Called when events are updated
+
+### View Configuration
+
+- `initialView?: CalendarView` - Initial view to display (`'dayGridMonth'` | `'timeGridWeek'` | `'timeGridDay'` | `'listWeek'`)
+- `views?: CalendarView[]` - Available views in the toolbar
+- `headerToolbar?: CalendarHeaderToolbar | boolean` - Header toolbar configuration
+
+### Calendar Behavior
+
+- `editable?: boolean` - Allow events to be edited (default: `false`)
+- `selectable?: boolean` - Allow date/time selection (default: `false`)
+- `selectMirror?: boolean` - Show selection preview (default: `true`)
+- `eventResizable?: boolean` - Allow event resizing (default: `false`)
+- `eventDraggable?: boolean` - Allow event dragging (default: `false`)
+- `dayMaxEvents?: boolean | number` - Limit events shown per day (default: `true`)
+
+### Styling & Layout
+
+- `height?: string | number` - Calendar height (default: `'auto'`)
+- `aspectRatio?: number` - Calendar aspect ratio
+- `containerProps?: StackProps` - Props for the container Stack component
+
+### Localization
+
+- `locale?: string` - Language locale (default: `'en'`)
+- `timezone?: string` - Timezone (default: `'local'`)
+- `firstDayOfWeek?: 0 | 1 | 2 | 3 | 4 | 5 | 6` - First day of week (default: `0` for Sunday)
+
+### Custom Rendering
+
+- `eventContent?: (eventInfo) => React.ReactNode` - Custom event content renderer
+- `dayCellContent?: (dayInfo) => React.ReactNode` - Custom day cell content renderer
+
+### Navigation
+
+- `showNavigationButtons?: boolean` - Show prev/next buttons (default: `true`)
+- `showViewSwitcher?: boolean` - Show view switcher buttons (default: `true`)
+- `showToday?: boolean` - Show today button (default: `true`)
+
+### Advanced
+
+- `weekends?: boolean` - Show weekend days (default: `true`)
+- `businessHours?: any` - Business hours configuration
+- `eventConstraint?: any` - Constraints for event placement
+- `selectConstraint?: any` - Constraints for date selection
+
+## Event Object Structure
+
+```tsx
+interface CalendarEvent {
+  id: string | number;
+  title: string;
+  start: Date | string;
+  end?: Date | string;
+  allDay?: boolean;
+  backgroundColor?: string;
+  borderColor?: string;
+  textColor?: string;
+  extendedProps?: {
+    [key: string]: any;
+  };
+}
+```
+
+## Examples
+
+### Interactive Calendar
+
+```tsx
+<Calendar
+  events={events}
+  height="600px"
+  editable={true}
+  selectable={true}
+  eventResizable={true}
+  eventDraggable={true}
+  onEventClick={(eventInfo) => {
+    console.log('Event clicked:', eventInfo.event.title);
+  }}
+  onDateSelect={(selectInfo) => {
+    const title = prompt('Event title:');
+    if (title) {
+      // Add new event logic
+    }
+  }}
+/>
+```
+
+### Custom Header Toolbar
+
+```tsx
+<Calendar
+  events={events}
+  headerToolbar={{
+    left: 'prev,next today',
+    center: 'title',
+    right: 'dayGridMonth,timeGridWeek',
+  }}
+/>
+```
+
+### Business Hours
+
+```tsx
+<Calendar
+  events={events}
+  initialView="timeGridWeek"
+  businessHours={{
+    daysOfWeek: [1, 2, 3, 4, 5], // Monday - Friday
+    startTime: '09:00',
+    endTime: '17:00',
+  }}
+  selectConstraint="businessHours"
+  eventConstraint="businessHours"
+/>
+```
+
+### Custom Event Rendering
+
+```tsx
+<Calendar
+  events={events}
+  eventContent={(eventInfo) => (
+    <div style={{ padding: '2px 4px' }}>
+      <div style={{ fontWeight: 'bold' }}>{eventInfo.event.title}</div>
+      <div style={{ fontSize: '0.8em' }}>
+        📍 {eventInfo.event.extendedProps.location}
+      </div>
+    </div>
+  )}
+/>
+```
+
+## Utility Functions
+
+The Calendar component comes with helpful utility functions:
+
+### Generate Recurring Events
+
+```tsx
+import { generateRecurringEvents } from '@campxdev/react-blueprint';
+
+const recurringEvents = generateRecurringEvents({
+  title: 'Daily Standup',
+  startTime: '09:00',
+  endTime: '09:30',
+  startDate: new Date(),
+  daysOfWeek: [1, 2, 3, 4, 5], // Weekdays only
+  backgroundColor: '#1976d2',
+});
+```
+
+### Generate Business Events
+
+```tsx
+import { generateBusinessEvents } from '@campxdev/react-blueprint';
+
+const businessEvents = generateBusinessEvents(new Date());
+```
+
+### Event Statistics
+
+```tsx
+import { calculateEventStats } from '@campxdev/react-blueprint';
+
+const stats = calculateEventStats(events);
+console.log(stats.totalEvents, stats.averageEventsPerDay);
+```
+
+### Export to CSV
+
+```tsx
+import { exportEventsToCSV } from '@campxdev/react-blueprint';
+
+const csvContent = exportEventsToCSV(events);
+// Download or save the CSV content
+```
+
+## Theme Integration
+
+The Calendar component fully integrates with your MUI theme:
+
+- Uses `theme.palette.surface.*` for backgrounds
+- Uses `theme.palette.text.*` for text colors
+- Uses `theme.palette.primary.*` for accent colors
+- Responds to `theme.breakpoints.*` for responsive design
+- Supports light/dark mode switching
+
+## Responsive Behavior
+
+The calendar automatically adapts to different screen sizes:
+
+- **Desktop**: Full toolbar with all view options
+- **Tablet**: Stacked toolbar on medium screens
+- **Mobile**: Compact toolbar with smaller buttons and text
+
+## Accessibility
+
+The Calendar component includes:
+
+- ARIA labels and roles
+- Keyboard navigation support
+- Focus management
+- Screen reader compatibility
+- High contrast mode support
+
+## Browser Support
+
+- Chrome 90+
+- Firefox 88+
+- Safari 14+
+- Edge 90+
+
+## TypeScript Support
+
+The Calendar component is fully typed with TypeScript, including:
+
+- Event interfaces
+- Handler function types
+- Configuration options
+- Utility function types
+
+## Performance
+
+The Calendar component is optimized for performance:
+
+- Event memoization
+- Efficient re-rendering
+- Lazy loading of plugins
+- Minimal bundle size impact
+
+## Troubleshooting
+
+### Events not showing
+
+- Ensure events have required `id`, `title`, and `start` properties
+- Check date format (ISO string or Date object)
+- Verify event dates are within the calendar view range
+
+### Styling issues
+
+- Check theme integration
+- Ensure proper CSS imports
+- Verify responsive breakpoints
+
+### Event handlers not firing
+
+- Check event prop names match the interface
+- Ensure calendar is in editable mode for interaction events
+- Verify handler functions are properly bound

package/src/components/Navigation/Calendar/index.ts

@@ -0,0 +1,3 @@
+export * from './Calendar';
+export * from './types';
+export * from './utils';

package/src/components/Navigation/Calendar/styles.tsx

@@ -0,0 +1,222 @@
+import { alpha, Box, Stack, styled } from '@mui/material';
+
+export const StyledCalendarContainer = styled(Stack, {
+  shouldForwardProp: (prop) => prop !== 'height' && prop !== 'aspectRatio',
+})<{
+  height?: string | number;
+  aspectRatio?: number;
+}>(({ theme, height, aspectRatio }) => ({
+  backgroundColor: theme.palette.surface.paperBackground,
+  borderRadius: theme.shape?.borderRadius || '8px',
+  overflow: 'hidden',
+  border: `1px solid ${theme.palette.border.primary}`,
+  height: height || 'auto',
+  aspectRatio: aspectRatio || 'auto',
+
+  // FullCalendar specific overrides
+  '& .fc': {
+    height: '100%',
+    fontFamily: theme.typography.fontFamily,
+    fontSize: theme.typography.body2.fontSize,
+  },
+
+  // Header styling
+  '& .fc-header-toolbar': {
+    backgroundColor: theme.palette.surface.defaultBackground,
+    padding: theme.spacing(2),
+    margin: 0,
+    borderBottom: `1px solid ${theme.palette.border.primary}`,
+
+    '& .fc-button-group': {
+      '& .fc-button': {
+        backgroundColor: theme.palette.primary.main,
+        borderColor: theme.palette.primary.main,
+        color: theme.palette.text.primaryContrast,
+        fontWeight: theme.typography.button.fontWeight,
+        textTransform: 'none',
+        borderRadius: theme.shape?.borderRadius || '6px',
+        padding: '6px 12px',
+        marginRight: '4px',
+
+        '&:hover': {
+          backgroundColor: theme.palette.primary.dark,
+          borderColor: theme.palette.primary.dark,
+        },
+
+        '&:focus': {
+          boxShadow: `0 0 0 2px ${theme.palette.primary.light}`,
+        },
+
+        '&.fc-button-active': {
+          backgroundColor: theme.palette.primary.dark,
+          borderColor: theme.palette.primary.dark,
+        },
+
+        '&:disabled': {
+          backgroundColor: theme.palette.border.primary,
+          borderColor: theme.palette.border.primary,
+          color: theme.palette.text.tertiary,
+        },
+      },
+    },
+
+    '& .fc-toolbar-title': {
+      color: theme.palette.text.primary,
+      fontSize: theme.typography.h5.fontSize,
+      fontWeight: theme.typography.h5.fontWeight,
+      margin: 0,
+    },
+  },
+
+  // Day header styling
+  '& .fc-col-header': {
+    backgroundColor: theme.palette.surface.defaultBackground,
+    borderBottom: `1px solid ${theme.palette.border.primary}`,
+
+    '& .fc-col-header-cell': {
+      padding: theme.spacing(1),
+
+      '& .fc-col-header-cell-cushion': {
+        color: theme.palette.text.secondary,
+        fontWeight: theme.typography.subtitle2.fontWeight,
+        textDecoration: 'none',
+        fontSize: theme.typography.caption.fontSize,
+        textTransform: 'uppercase',
+      },
+    },
+  },
+
+  // Day cells styling
+  '& .fc-daygrid-day': {
+    backgroundColor: theme.palette.surface.paperBackground,
+    borderColor: theme.palette.border.primary,
+
+    '&.fc-day-today': {
+      backgroundColor: alpha(theme.palette.primary.light, 0.1),
+    },
+
+    '& .fc-daygrid-day-number': {
+      color: theme.palette.text.primary,
+      textDecoration: 'none',
+      padding: theme.spacing(0.5, 1),
+      fontSize: theme.typography.body2.fontSize,
+
+      '&:hover': {
+        backgroundColor: theme.palette.surface.grey,
+        borderRadius: '4px',
+      },
+    },
+
+    '& .fc-daygrid-day-top': {
+      display: 'flex',
+      justifyContent: 'flex-end',
+      padding: theme.spacing(0.5),
+    },
+  },
+
+  // Event styling
+  '& .fc-event': {
+    backgroundColor: theme.palette.primary.main,
+    borderColor: theme.palette.primary.main,
+    color: theme.palette.text.primaryContrast,
+    borderRadius: '4px',
+    border: 'none',
+
+    '&:hover': {
+      backgroundColor: theme.palette.primary.dark,
+    },
+  },
+
+  // Time grid styling
+  '& .fc-timegrid': {
+    '& .fc-timegrid-slot': {
+      borderColor: theme.palette.border.primary,
+    },
+
+    '& .fc-timegrid-col.fc-day-today': {
+      backgroundColor: alpha(theme.palette.primary.light, 0.08),
+    },
+  },
+
+  // List view styling
+  '& .fc-list': {
+    '& .fc-list-day': {
+      backgroundColor: theme.palette.surface.defaultBackground,
+    },
+
+    '& .fc-list-event': {
+      borderColor: theme.palette.border.primary,
+
+      '&:hover': {
+        backgroundColor: theme.palette.surface.grey,
+      },
+    },
+  },
+
+  // More link styling
+  '& .fc-more-link': {
+    color: theme.palette.primary.main,
+
+    '&:hover': {
+      color: theme.palette.primary.dark,
+    },
+  },
+
+  // Popover styling
+  '& .fc-popover': {
+    backgroundColor: theme.palette.surface.paperBackground,
+    border: `1px solid ${theme.palette.border.primary}`,
+    borderRadius: theme.shape?.borderRadius || '8px',
+    boxShadow: theme.shadows[8],
+
+    '& .fc-popover-header': {
+      backgroundColor: theme.palette.surface.defaultBackground,
+      borderBottom: `1px solid ${theme.palette.border.primary}`,
+    },
+  },
+
+  // Responsive design
+  [theme.breakpoints.down('md')]: {
+    '& .fc-header-toolbar': {
+      flexDirection: 'column',
+      gap: theme.spacing(1),
+    },
+
+    '& .fc-button-group .fc-button': {
+      padding: '4px 8px',
+    },
+  },
+
+  [theme.breakpoints.down('sm')]: {
+    '& .fc-event': {
+      fontSize: '0.7rem',
+    },
+  },
+}));
+
+export const StyledCalendarWrapper = styled(Box)(({ theme }) => ({
+  position: 'relative',
+  width: '100%',
+
+  // Custom scrollbar for calendar content
+  '& .fc-scroller': {
+    '&::-webkit-scrollbar': {
+      width: '6px',
+      height: '6px',
+    },
+
+    '&::-webkit-scrollbar-track': {
+      backgroundColor: theme.palette.surface.defaultBackground,
+      borderRadius: '3px',
+    },
+
+    '&::-webkit-scrollbar-thumb': {
+      backgroundColor: theme.palette.border.secondary,
+      borderRadius: '3px',
+
+      '&:hover': {
+        backgroundColor: theme.palette.surface.grey,
+      },
+    },
+  },
+}));

package/src/components/Navigation/Calendar/types.ts

@@ -0,0 +1,120 @@
+import { EventApi } from '@fullcalendar/core';
+import { StackProps } from '@mui/material';
+
+export interface CalendarEvent {
+  id: string | number;
+  title: string;
+  start: Date | string;
+  end?: Date | string;
+  allDay?: boolean;
+  backgroundColor?: string;
+  borderColor?: string;
+  textColor?: string;
+  extendedProps?: {
+    [key: string]: any;
+  };
+}
+
+export interface CalendarEventClickInfo {
+  event: EventApi;
+  jsEvent: MouseEvent;
+  view: any;
+}
+
+export interface CalendarDateSelectInfo {
+  start: Date;
+  end: Date;
+  allDay: boolean;
+  jsEvent: MouseEvent;
+  view: any;
+}
+
+export interface CalendarEventDropInfo {
+  event: EventApi;
+  delta: any;
+  revert: () => void;
+  jsEvent: Event;
+  view: any;
+}
+
+export interface CalendarEventResizeInfo {
+  event: EventApi;
+  startDelta: any;
+  endDelta: any;
+  revert: () => void;
+  jsEvent: Event;
+  view: any;
+}
+
+export interface CalendarDateClickInfo {
+  date: Date;
+  dateStr: string;
+  allDay: boolean;
+  dayEl: HTMLElement;
+  jsEvent: MouseEvent;
+  view: any;
+}
+
+export type CalendarView =
+  | 'dayGridMonth'
+  | 'timeGridWeek'
+  | 'timeGridDay'
+  | 'listWeek';
+
+export interface CalendarHeaderToolbar {
+  left?: string;
+  center?: string;
+  right?: string;
+}
+
+export interface CalendarProps {
+  // Event data
+  events?: CalendarEvent[];
+
+  // Event handlers
+  onEventClick?: (eventInfo: CalendarEventClickInfo) => void;
+  onEventDrop?: (eventInfo: CalendarEventDropInfo) => void;
+  onEventResize?: (eventInfo: CalendarEventResizeInfo) => void;
+  onDateClick?: (dateInfo: CalendarDateClickInfo) => void;
+  onDateSelect?: (selectInfo: CalendarDateSelectInfo) => void;
+  onEventsSet?: (events: EventApi[]) => void;
+
+  // View configuration
+  initialView?: CalendarView;
+  views?: CalendarView[];
+  headerToolbar?: CalendarHeaderToolbar | boolean;
+
+  // Calendar behavior
+  editable?: boolean;
+  selectable?: boolean;
+  selectMirror?: boolean;
+  eventResizable?: boolean;
+  eventDraggable?: boolean;
+  dayMaxEvents?: boolean | number;
+
+  // Styling & layout
+  height?: string | number;
+  aspectRatio?: number;
+  containerProps?: StackProps;
+
+  // Localization
+  locale?: string;
+  timezone?: string;
+  firstDayOfWeek?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
+
+  // Custom rendering
+  eventContent?: (eventInfo: any) => React.ReactNode;
+  dayCellContent?: (dayInfo: any) => React.ReactNode;
+
+  // Navigation
+  showNavigationButtons?: boolean;
+  showViewSwitcher?: boolean;
+  showToday?: boolean;
+
+  // Advanced
+  calendarRef?: React.RefObject<any>;
+  weekends?: boolean;
+  businessHours?: any;
+  eventConstraint?: any;
+  selectConstraint?: any;
+}