kalendly 0.1.0 → 0.1.2

package/README.md

@@ -8,11 +8,20 @@ A universal calendar scheduler component that works seamlessly across React, Vue
 - 📱 **Responsive**: Mobile-friendly design that matches your existing Vue implementation
 - 🎨 **Customizable**: Easy to theme and customize with CSS variables
 - 🔒 **Type Safe**: Full TypeScript support
-- 📅 **Event Management**: Add, display, and manage events
+- 📅 **Event Management**: Add, display, and manage events with rich metadata
+- 🔔 **Advanced Features**: Recurring events, reminders, categories, priorities, and collaboration
 - 🌐 **Accessible**: Built with accessibility in mind
 - 📦 **Tree Shakeable**: Import only what you need
 - 🎯 **Design Consistent**: Matches the original Vue calendar design and feel
 
+## Live Examples
+
+Check out the interactive examples: [https://kalendly.netlify.app](https://kalendly.netlify.app)
+
+- [Vanilla JavaScript](https://kalendly.netlify.app/vanilla)
+- [React](https://kalendly.netlify.app/react)
+- [Vue](https://kalendly.netlify.app/vue)
+
 ## Installation
 
 ```bash
@@ -264,30 +273,130 @@ export default App;
 
 ### Props
 
-| Prop            | Type                                    | Default            | Description                             |
-| --------------- | --------------------------------------- | ------------------ | --------------------------------------- |
-| `events`        | `CalendarEvent[]`                       | `[]`               | Array of events to display              |
-| `initialDate`   | `Date`                                  | `new Date()`       | Initial date to display                 |
-| `minYear`       | `number`                                | `currentYear - 30` | Minimum selectable year                 |
-| `maxYear`       | `number`                                | `currentYear + 10` | Maximum selectable year                 |
-| `weekStartsOn`  | `0 \| 1`                                | `0`                | Week start day (0 = Sunday, 1 = Monday) |
-| `onDateSelect`  | `(date: Date) => void`                  | -                  | Callback when date is selected          |
-| `onEventClick`  | `(event: CalendarEvent) => void`        | -                  | Callback when event is clicked          |
-| `onMonthChange` | `(year: number, month: number) => void` | -                  | Callback when month changes             |
+| Prop             | Type                                    | Default            | Description                             |
+| ---------------- | --------------------------------------- | ------------------ | --------------------------------------- |
+| `events`         | `CalendarEvent[]`                       | `[]`               | Array of events to display              |
+| `initialDate`    | `Date`                                  | `new Date()`       | Initial date to display                 |
+| `minYear`        | `number`                                | `currentYear - 30` | Minimum selectable year                 |
+| `maxYear`        | `number`                                | `currentYear + 10` | Maximum selectable year                 |
+| `weekStartsOn`   | `0 \| 1`                                | `0`                | Week start day (0 = Sunday, 1 = Monday) |
+| `categoryColors` | `CategoryColorMap`                      | `{}`               | Custom colors for event categories      |
+| `onDateSelect`   | `(date: Date) => void`                  | -                  | Callback when date is selected          |
+| `onEventClick`   | `(event: CalendarEvent) => void`        | -                  | Callback when event is clicked          |
+| `onMonthChange`  | `(year: number, month: number) => void` | -                  | Callback when month changes             |
 
 ### CalendarEvent Interface
 
 ```typescript
 interface CalendarEvent {
+  // Required fields
   id: string | number;
   name: string;
   date: string | Date;
+
+  // Time fields
+  startTime?: string; // e.g., "09:00", "14:30"
+  endTime?: string; // e.g., "10:00", "16:00"
+  allDay?: boolean; // True for all-day events
+
+  // Display & categorization
   description?: string;
-  color?: string;
-  [key: string]: any;
+  color?: string; // Custom event color
+  category?:
+    | 'work'
+    | 'personal'
+    | 'meeting'
+    | 'deadline'
+    | 'appointment'
+    | 'other';
+  location?: string; // Event location
+  url?: string; // Related URL or meeting link
+
+  // Status & priority
+  status?: 'scheduled' | 'completed' | 'cancelled' | 'tentative';
+  priority?: 'low' | 'medium' | 'high';
+
+  // Collaboration
+  attendees?: string[]; // List of attendee names/emails
+  organizer?: string; // Event organizer
+
+  // Reminders & recurrence
+  reminders?: number[]; // Minutes before event to remind (e.g., [15, 60])
+  recurring?: {
+    frequency: 'daily' | 'weekly' | 'monthly' | 'yearly';
+    interval?: number; // Every X days/weeks/months/years
+    endDate?: string | Date; // When recurrence ends
+    daysOfWeek?: number[]; // For weekly recurrence (0 = Sunday)
+  };
+
+  // Metadata
+  notes?: string; // Additional notes
+  tags?: string[]; // Event tags
+  createdAt?: string | Date; // Creation timestamp
+  updatedAt?: string | Date; // Last update timestamp
+
+  // Flexibility for custom fields
+  [key: string]: unknown;
 }
 ```
 
+#### Example with Enhanced Fields
+
+```typescript
+const events = [
+  {
+    id: 1,
+    name: 'Team Standup',
+    date: '2025-01-15',
+    startTime: '09:00',
+    endTime: '09:30',
+    category: 'meeting',
+    location: 'Conference Room A',
+    url: 'https://meet.google.com/abc-defg-hij',
+    attendees: ['john@example.com', 'jane@example.com'],
+    organizer: 'team-lead@example.com',
+    priority: 'high',
+    status: 'scheduled',
+    reminders: [15, 60],
+    recurring: {
+      frequency: 'daily',
+      interval: 1,
+      daysOfWeek: [1, 2, 3, 4, 5], // Mon-Fri
+      endDate: '2025-12-31',
+    },
+    tags: ['team', 'sync'],
+  },
+  {
+    id: 2,
+    name: 'Project Deadline',
+    date: '2025-01-20',
+    allDay: true,
+    category: 'deadline',
+    priority: 'high',
+    status: 'scheduled',
+    description: 'Final submission for Q1 project',
+    notes: 'Make sure all tests pass before submission',
+  },
+];
+```
+
+#### Category Colors
+
+You can customize colors for different event categories:
+
+```typescript
+const categoryColors = {
+  work: '#4CAF50',
+  personal: '#2196F3',
+  meeting: '#FF9800',
+  deadline: '#F44336',
+  appointment: '#9C27B0',
+  other: '#607D8B'
+};
+
+<Calendar events={events} categoryColors={categoryColors} />
+```
+
 ## Framework-Specific Features
 
 ### React Props
@@ -470,11 +579,29 @@ import type { CalendarEvent, CalendarProps, CalendarState } from 'kalendly';
 
 ## Contributing
 
-1. Fork the repository
-2. Create your feature branch (`git checkout -b feature/amazing-feature`)
-3. Commit your changes (`git commit -m 'Add some amazing feature'`)
-4. Push to the branch (`git push origin feature/amazing-feature`)
-5. Open a Pull Request
+We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for detailed information on:
+
+- Development setup
+- Project structure
+- Building and testing
+- Running examples
+- Submitting pull requests
+- Release process
+
+Quick start:
+
+```bash
+# Clone and install
+git clone https://github.com/callezenwaka/kalendly.git
+cd kalendly
+npm install
+
+# Run tests
+npm test
+
+# Run examples locally
+npm run dev:examples
+```
 
 ## License
 
@@ -482,11 +609,10 @@ MIT © Callis Ezenwaka
 
 ## Changelog
 
-### 1.0.0
+See [CHANGELOG.md](CHANGELOG.md) for detailed release notes and version history.
+
+### Recent Updates
 
-- Initial release
-- React, Vue, and React Native support
-- TypeScript definitions
-- Core calendar engine
-- Event management
-- Responsive design
+- **v0.1.2** (Upcoming): Enhanced event parameters with structured metadata, categories, recurrence, collaboration features, and Netlify deployment
+- **v0.1.1**: Pre-commit hooks and trusted publishing with OIDC
+- **v0.1.0**: Initial release with React, Vue, React Native, and Vanilla JavaScript support

package/dist/core/index.d.mts

@@ -2,9 +2,30 @@ interface CalendarEvent {
     id: string | number;
     name: string;
     date: string | Date;
+    startTime?: string;
+    endTime?: string;
+    allDay?: boolean;
     description?: string;
     color?: string;
-    [key: string]: any;
+    category?: 'work' | 'personal' | 'meeting' | 'deadline' | 'appointment' | 'other';
+    location?: string;
+    url?: string;
+    status?: 'scheduled' | 'completed' | 'cancelled' | 'tentative';
+    priority?: 'low' | 'medium' | 'high';
+    attendees?: string[];
+    organizer?: string;
+    reminders?: number[];
+    recurring?: {
+        frequency: 'daily' | 'weekly' | 'monthly' | 'yearly';
+        interval?: number;
+        endDate?: string | Date;
+        daysOfWeek?: number[];
+    };
+    notes?: string;
+    tags?: string[];
+    createdAt?: string | Date;
+    updatedAt?: string | Date;
+    [key: string]: unknown;
 }
 interface CalendarDate {
     date: Date;
@@ -21,12 +42,16 @@ interface CalendarState {
     selectedDayIndex: number | null;
     tasks: CalendarEvent[];
 }
+interface CategoryColorMap {
+    [category: string]: string;
+}
 interface CalendarConfig {
     events: CalendarEvent[];
     initialDate?: Date;
     minYear?: number;
     maxYear?: number;
     weekStartsOn?: 0 | 1;
+    categoryColors?: CategoryColorMap;
 }
 interface CalendarActions {
     next: () => void;
@@ -62,55 +87,31 @@ interface CalendarProps {
 
 declare const MONTHS: string[];
 declare const DAYS: string[];
-/**
- * Normalizes a date to midnight (00:00:00) for comparison purposes
- */
 declare function normalizeDate(date: Date): Date;
-/**
- * Checks if two dates are the same day
- */
 declare function isSameDay(date1: Date, date2: Date): boolean;
-/**
- * Checks if a date is today
- */
 declare function isToday(date: Date): boolean;
-/**
- * Generates an array of years for the year selector
- */
 declare function generateYears(minYear?: number, maxYear?: number): number[];
-/**
- * Gets events for a specific date
- */
 declare function getEventsForDate(events: CalendarEvent[], date: Date): CalendarEvent[];
-/**
- * Checks if a date has any events
- */
 declare function hasEvents(events: CalendarEvent[], date: Date): boolean;
-/**
- * Generates calendar dates for a given month and year
- */
 declare function generateCalendarDates(year: number, month: number, events?: CalendarEvent[], weekStartsOn?: 0 | 1): (CalendarDate | null)[][];
-/**
- * Gets the popup position class based on the selected day index
- */
 declare function getPopupPositionClass(selectedDayIndex: number | null): string;
-/**
- * Gets CSS classes for a calendar cell
- */
 declare function getCellClasses(calendarDate: CalendarDate | null): string[];
-/**
- * Formats a date for display
- */
 declare function formatDateForDisplay(date: Date): string;
-/**
- * Gets month and year text for display
- */
 declare function getMonthYearText(year: number, month: number): string;
+declare function formatTimeRange(event: CalendarEvent): string;
+declare function formatAttendees(attendees?: string[]): string;
+declare function sortEventsByTime(events: CalendarEvent[]): CalendarEvent[];
+declare const DEFAULT_CATEGORY_COLORS: CategoryColorMap;
+declare function getDefaultEventColor(category?: string, customColors?: CategoryColorMap): string;
+declare function mergeCategoryColors(customColors?: CategoryColorMap): CategoryColorMap;
+declare function isValidHexColor(color: string): boolean;
+declare function getCategoryColor(category: string, customColors?: CategoryColorMap): string;
 
 declare class CalendarEngine {
     private state;
     private config;
     private listeners;
+    private categoryColors;
     constructor(config: CalendarConfig);
     /**
      * Subscribe to state changes
@@ -172,10 +173,26 @@ declare class CalendarEngine {
      * Clear selected date
      */
     clearSelection(): void;
+    /**
+     * Get category color (with custom colors support)
+     */
+    getCategoryColor(category?: string): string;
+    /**
+     * Update category colors dynamically
+     */
+    updateCategoryColors(colors: CategoryColorMap): void;
+    /**
+     * Get all category colors
+     */
+    getCategoryColors(): CategoryColorMap;
+    /**
+     * Register a new category with color
+     */
+    registerCategory(name: string, color: string): void;
     /**
      * Destroy the engine and cleanup listeners
      */
     destroy(): void;
 }
 
-export { type CalendarActions, type CalendarConfig, type CalendarDate, CalendarEngine, type CalendarEvent, type CalendarEventHandler, type CalendarProps, type CalendarState, type CalendarViewModel, DAYS, MONTHS, type PopupPosition, formatDateForDisplay, generateCalendarDates, generateYears, getCellClasses, getEventsForDate, getMonthYearText, getPopupPositionClass, hasEvents, isSameDay, isToday, normalizeDate };
+export { type CalendarActions, type CalendarConfig, type CalendarDate, CalendarEngine, type CalendarEvent, type CalendarEventHandler, type CalendarProps, type CalendarState, type CalendarViewModel, type CategoryColorMap, DAYS, DEFAULT_CATEGORY_COLORS, MONTHS, type PopupPosition, formatAttendees, formatDateForDisplay, formatTimeRange, generateCalendarDates, generateYears, getCategoryColor, getCellClasses, getDefaultEventColor, getEventsForDate, getMonthYearText, getPopupPositionClass, hasEvents, isSameDay, isToday, isValidHexColor, mergeCategoryColors, normalizeDate, sortEventsByTime };

package/dist/core/index.d.ts

@@ -2,9 +2,30 @@ interface CalendarEvent {
     id: string | number;
     name: string;
     date: string | Date;
+    startTime?: string;
+    endTime?: string;
+    allDay?: boolean;
     description?: string;
     color?: string;
-    [key: string]: any;
+    category?: 'work' | 'personal' | 'meeting' | 'deadline' | 'appointment' | 'other';
+    location?: string;
+    url?: string;
+    status?: 'scheduled' | 'completed' | 'cancelled' | 'tentative';
+    priority?: 'low' | 'medium' | 'high';
+    attendees?: string[];
+    organizer?: string;
+    reminders?: number[];
+    recurring?: {
+        frequency: 'daily' | 'weekly' | 'monthly' | 'yearly';
+        interval?: number;
+        endDate?: string | Date;
+        daysOfWeek?: number[];
+    };
+    notes?: string;
+    tags?: string[];
+    createdAt?: string | Date;
+    updatedAt?: string | Date;
+    [key: string]: unknown;
 }
 interface CalendarDate {
     date: Date;
@@ -21,12 +42,16 @@ interface CalendarState {
     selectedDayIndex: number | null;
     tasks: CalendarEvent[];
 }
+interface CategoryColorMap {
+    [category: string]: string;
+}
 interface CalendarConfig {
     events: CalendarEvent[];
     initialDate?: Date;
     minYear?: number;
     maxYear?: number;
     weekStartsOn?: 0 | 1;
+    categoryColors?: CategoryColorMap;
 }
 interface CalendarActions {
     next: () => void;
@@ -62,55 +87,31 @@ interface CalendarProps {
 
 declare const MONTHS: string[];
 declare const DAYS: string[];
-/**
- * Normalizes a date to midnight (00:00:00) for comparison purposes
- */
 declare function normalizeDate(date: Date): Date;
-/**
- * Checks if two dates are the same day
- */
 declare function isSameDay(date1: Date, date2: Date): boolean;
-/**
- * Checks if a date is today
- */
 declare function isToday(date: Date): boolean;
-/**
- * Generates an array of years for the year selector
- */
 declare function generateYears(minYear?: number, maxYear?: number): number[];
-/**
- * Gets events for a specific date
- */
 declare function getEventsForDate(events: CalendarEvent[], date: Date): CalendarEvent[];
-/**
- * Checks if a date has any events
- */
 declare function hasEvents(events: CalendarEvent[], date: Date): boolean;
-/**
- * Generates calendar dates for a given month and year
- */
 declare function generateCalendarDates(year: number, month: number, events?: CalendarEvent[], weekStartsOn?: 0 | 1): (CalendarDate | null)[][];
-/**
- * Gets the popup position class based on the selected day index
- */
 declare function getPopupPositionClass(selectedDayIndex: number | null): string;
-/**
- * Gets CSS classes for a calendar cell
- */
 declare function getCellClasses(calendarDate: CalendarDate | null): string[];
-/**
- * Formats a date for display
- */
 declare function formatDateForDisplay(date: Date): string;
-/**
- * Gets month and year text for display
- */
 declare function getMonthYearText(year: number, month: number): string;
+declare function formatTimeRange(event: CalendarEvent): string;
+declare function formatAttendees(attendees?: string[]): string;
+declare function sortEventsByTime(events: CalendarEvent[]): CalendarEvent[];
+declare const DEFAULT_CATEGORY_COLORS: CategoryColorMap;
+declare function getDefaultEventColor(category?: string, customColors?: CategoryColorMap): string;
+declare function mergeCategoryColors(customColors?: CategoryColorMap): CategoryColorMap;
+declare function isValidHexColor(color: string): boolean;
+declare function getCategoryColor(category: string, customColors?: CategoryColorMap): string;
 
 declare class CalendarEngine {
     private state;
     private config;
     private listeners;
+    private categoryColors;
     constructor(config: CalendarConfig);
     /**
      * Subscribe to state changes
@@ -172,10 +173,26 @@ declare class CalendarEngine {
      * Clear selected date
      */
     clearSelection(): void;
+    /**
+     * Get category color (with custom colors support)
+     */
+    getCategoryColor(category?: string): string;
+    /**
+     * Update category colors dynamically
+     */
+    updateCategoryColors(colors: CategoryColorMap): void;
+    /**
+     * Get all category colors
+     */
+    getCategoryColors(): CategoryColorMap;
+    /**
+     * Register a new category with color
+     */
+    registerCategory(name: string, color: string): void;
     /**
      * Destroy the engine and cleanup listeners
      */
     destroy(): void;
 }
 
-export { type CalendarActions, type CalendarConfig, type CalendarDate, CalendarEngine, type CalendarEvent, type CalendarEventHandler, type CalendarProps, type CalendarState, type CalendarViewModel, DAYS, MONTHS, type PopupPosition, formatDateForDisplay, generateCalendarDates, generateYears, getCellClasses, getEventsForDate, getMonthYearText, getPopupPositionClass, hasEvents, isSameDay, isToday, normalizeDate };
+export { type CalendarActions, type CalendarConfig, type CalendarDate, CalendarEngine, type CalendarEvent, type CalendarEventHandler, type CalendarProps, type CalendarState, type CalendarViewModel, type CategoryColorMap, DAYS, DEFAULT_CATEGORY_COLORS, MONTHS, type PopupPosition, formatAttendees, formatDateForDisplay, formatTimeRange, generateCalendarDates, generateYears, getCategoryColor, getCellClasses, getDefaultEventColor, getEventsForDate, getMonthYearText, getPopupPositionClass, hasEvents, isSameDay, isToday, isValidHexColor, mergeCategoryColors, normalizeDate, sortEventsByTime };

package/dist/core/index.js

@@ -22,18 +22,26 @@ var index_exports = {};
 __export(index_exports, {
   CalendarEngine: () => CalendarEngine,
   DAYS: () => DAYS,
+  DEFAULT_CATEGORY_COLORS: () => DEFAULT_CATEGORY_COLORS,
   MONTHS: () => MONTHS,
+  formatAttendees: () => formatAttendees,
   formatDateForDisplay: () => formatDateForDisplay,
+  formatTimeRange: () => formatTimeRange,
   generateCalendarDates: () => generateCalendarDates,
   generateYears: () => generateYears,
+  getCategoryColor: () => getCategoryColor,
   getCellClasses: () => getCellClasses,
+  getDefaultEventColor: () => getDefaultEventColor,
   getEventsForDate: () => getEventsForDate,
   getMonthYearText: () => getMonthYearText,
   getPopupPositionClass: () => getPopupPositionClass,
   hasEvents: () => hasEvents,
   isSameDay: () => isSameDay,
   isToday: () => isToday,
-  normalizeDate: () => normalizeDate
+  isValidHexColor: () => isValidHexColor,
+  mergeCategoryColors: () => mergeCategoryColors,
+  normalizeDate: () => normalizeDate,
+  sortEventsByTime: () => sortEventsByTime
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -150,12 +158,70 @@ function formatDateForDisplay(date) {
 function getMonthYearText(year, month) {
   return `${MONTHS[month]} ${year}`;
 }
+function formatTimeRange(event) {
+  if (event.allDay || !event.startTime && !event.endTime) {
+    return "All day";
+  }
+  if (event.startTime && event.endTime) {
+    return `${event.startTime} - ${event.endTime}`;
+  }
+  if (event.startTime) {
+    return `${event.startTime}`;
+  }
+  return "";
+}
+function formatAttendees(attendees) {
+  if (!attendees || attendees.length === 0) return "";
+  if (attendees.length === 1) return attendees[0];
+  if (attendees.length === 2) return attendees.join(" and ");
+  return `${attendees.slice(0, -1).join(", ")}, and ${attendees[attendees.length - 1]}`;
+}
+function sortEventsByTime(events) {
+  return [...events].sort((a, b) => {
+    const aAllDay = a.allDay || !a.startTime && !a.endTime;
+    const bAllDay = b.allDay || !b.startTime && !b.endTime;
+    if (aAllDay && !bAllDay) return -1;
+    if (!aAllDay && bAllDay) return 1;
+    if (!a.startTime || !b.startTime) return 0;
+    return a.startTime.localeCompare(b.startTime);
+  });
+}
+var DEFAULT_CATEGORY_COLORS = {
+  work: "#3b82f6",
+  personal: "#8b5cf6",
+  meeting: "#10b981",
+  deadline: "#ef4444",
+  appointment: "#f59e0b",
+  other: "#6b7280"
+};
+function getDefaultEventColor(category, customColors) {
+  const colorMap = customColors || DEFAULT_CATEGORY_COLORS;
+  if (category && colorMap[category]) {
+    return colorMap[category];
+  }
+  return "#fc8917";
+}
+function mergeCategoryColors(customColors) {
+  return {
+    ...DEFAULT_CATEGORY_COLORS,
+    ...customColors
+  };
+}
+function isValidHexColor(color) {
+  return /^#([0-9A-F]{3}){1,2}$/i.test(color);
+}
+function getCategoryColor(category, customColors) {
+  const colorMap = mergeCategoryColors(customColors);
+  const color = colorMap[category] || colorMap.other || "#fc8917";
+  return isValidHexColor(color) ? color : "#fc8917";
+}
 
 // src/core/calendar-engine.ts
 var CalendarEngine = class {
   constructor(config) {
     this.listeners = /* @__PURE__ */ new Set();
     this.config = config;
+    this.categoryColors = mergeCategoryColors(config.categoryColors);
     const initialDate = config.initialDate || /* @__PURE__ */ new Date();
     this.state = {
       currentYear: initialDate.getFullYear(),
@@ -322,6 +388,33 @@ var CalendarEngine = class {
     this.state.tasks = [];
     this.notify();
   }
+  /**
+   * Get category color (with custom colors support)
+   */
+  getCategoryColor(category) {
+    if (!category) return "#fc8917";
+    return getCategoryColor(category, this.categoryColors);
+  }
+  /**
+   * Update category colors dynamically
+   */
+  updateCategoryColors(colors) {
+    this.categoryColors = mergeCategoryColors(colors);
+    this.notify();
+  }
+  /**
+   * Get all category colors
+   */
+  getCategoryColors() {
+    return { ...this.categoryColors };
+  }
+  /**
+   * Register a new category with color
+   */
+  registerCategory(name, color) {
+    this.categoryColors[name] = color;
+    this.notify();
+  }
   /**
    * Destroy the engine and cleanup listeners
    */
@@ -333,17 +426,25 @@ var CalendarEngine = class {
 0 && (module.exports = {
   CalendarEngine,
   DAYS,
+  DEFAULT_CATEGORY_COLORS,
   MONTHS,
+  formatAttendees,
   formatDateForDisplay,
+  formatTimeRange,
   generateCalendarDates,
   generateYears,
+  getCategoryColor,
   getCellClasses,
+  getDefaultEventColor,
   getEventsForDate,
   getMonthYearText,
   getPopupPositionClass,
   hasEvents,
   isSameDay,
   isToday,
-  normalizeDate
+  isValidHexColor,
+  mergeCategoryColors,
+  normalizeDate,
+  sortEventsByTime
 });
 //# sourceMappingURL=index.js.map