@ilamy/calendar 1.6.3 → 1.7.0

package/README.md

@@ -1,50 +1,116 @@
 # ilamy Calendar
 
-A powerful, full-featured React calendar component library built with TypeScript, Tailwind CSS, and modern React patterns. Features multiple calendar views, drag-and-drop support, recurring events, and comprehensive internationalization.
+[![NPM Version](https://img.shields.io/npm/v/@ilamy/calendar?style=flat-square&color=black)](https://www.npmjs.com/package/@ilamy/calendar)
+[![License](https://img.shields.io/npm/l/@ilamy/calendar?style=flat-square&color=black)](https://github.com/kcsujeet/ilamy-calendar/blob/main/LICENSE)
+[![Build Status](https://img.shields.io/github/actions/workflow/status/kcsujeet/ilamy-calendar/ci.yml?branch=main&style=flat-square)](https://github.com/kcsujeet/ilamy-calendar/actions)
 
-<img width="1643" height="873" alt="Screenshot 2025-08-05 at 9 46 41 AM" src="https://github.com/user-attachments/assets/d289f034-0d26-4a1c-a997-dfa1ad26aa7a" />
+A powerful, full-featured React calendar component library built with **TypeScript**, **Tailwind CSS 4**, and **Shadcn UI**. Designed for high-performance scheduling applications with full support for RFC 5545 recurring events, resource management, and drag-and-drop interactions.
 
-<img width="1663" height="872" alt="Screenshot 2025-10-13 at 4 24 29 PM" src="https://github.com/user-attachments/assets/ba0aa27e-373c-40ba-98c6-2d6fd767cb66" />
+<div align="center">
+  <img width="1643" height="873" alt="ilamy Calendar Month View" src="https://github.com/user-attachments/assets/d289f034-0d26-4a1c-a997-dfa1ad26aa7a" />
+  <p align="center"><i>Elegant month view with seamless event transitions</i></p>
+</div>
+
+---
 
 ## Features
 
-- 🗓️ **Multiple Views**: Month, Week, Day, and Year views with smooth transitions
-- 📊 **Resource Calendar**: Visualize and manage events across multiple resources with timeline layout
-- 🎯 **Drag & Drop**: Move events between dates and time slots with collision detection
-- 🔄 **RFC 5545 Recurring Events**: Full RRULE support with Google Calendar-style operations
-  - **RRULE Patterns**: Daily, Weekly, Monthly, Yearly with complex frequencies
-  - **Smart Operations**: Edit "this event", "this and following", or "all events"
-  - **Exception Handling**: EXDATE exclusions and modified instance support
-  - **rrule.js Integration**: Battle-tested library for robust recurrence generation
-- 📤 **iCalendar Export**: RFC 5545 compliant .ics file export with proper recurring event handling
-- 🌍 **Internationalization**: 100+ locales with dayjs and configurable week start days
-- 🎨 **Customizable Styling**:
-  - Flexible theming with Tailwind CSS and CSS variables
-  - Custom event rendering with render props
-  - Configurable colors, fonts, and spacing
-- ⚡ **Performance Optimized**:
-  - On-demand recurring event generation
-  - Efficient date range calculations
-  - Minimal re-renders with optimized React patterns
-- 📱 **Responsive Design**: Adaptive layouts for desktop, tablet, and mobile
-- 🔧 **Developer Experience**:
-  - Full TypeScript support with comprehensive type definitions
-  - IntelliSense and autocompletion
-  - Extensive JSDoc documentation
-  - Test-driven development with 100% test coverage
-- 🎛️ **Advanced Event Management**:
-  - All-day events with proper timezone handling
-  - Multi-day events with smart positioning
-  - Event validation and error handling
-  - Bulk operations and batch updates
+### Core Views
+- **Multiple Perspectives**: Month, Week, Day, and Year views.
+- **Fluid Navigation**: Smooth transitions between dates and views.
+- **Business Hours**: Customizable working hours with support for split shifts.
+
+### Resource Management
+- **Resource Timeline**: Visualize and manage events across multiple resources (rooms, people, equipment).
+- **Vertical & Horizontal Layouts**: Flexible resource views to fit any application design.
+- **Resource-Aware Validation**: Ensure events are correctly assigned and don't overlap where prohibited.
+
+### Recurring Events (RFC 5545)
+- **Full RRULE Support**: Daily, Weekly, Monthly, Yearly patterns with complex frequencies.
+- **Smart CRUD**: Google Calendar-style operations—edit "this event", "this and following", or "all events".
+- **Exclusion Dates**: Robust handling of EXDATE and modified instances within a series.
+- **iCalendar Export**: Export events to `.ics` files with strict RFC 5545 compliance.
+
+### Interactions & Globalization
+- **Timezones**: Full timezone support via `dayjs.tz` with automatic DST handling.
+- **Internationalization**: Support for 100+ locales with configurable week start days.
+- **Drag & Drop**: Move and resize events with precision using `@dnd-kit`.
+- **Responsive**: Adaptive layouts designed for desktop, tablet, and mobile.
+
+### Developer Experience
+- **Type Safety**: Written in TypeScript with comprehensive type definitions and IntelliSense support.
+- **Reliability**: 100% test coverage for all mission-critical date and recurrence logic.
+- **Theming**: Built on Tailwind CSS 4 variables for effortless branding and customization.
+- **Modern Stack**: Zero-config integration with React 19 and modern build tools.
+
+---
+
+## Installation
+
+Install the library and its peer dependencies using your preferred package manager:
+
+```bash
+# npm
+npm install @ilamy/calendar
+
+# bun
+bun add @ilamy/calendar
+
+# pnpm
+pnpm add @ilamy/calendar
+```
+
+> **Note**: This library requires **React 19+** and **Tailwind CSS 4+**.
+
+---
+
+## Quick Start
+
+```tsx
+import { IlamyCalendar } from '@ilamy/calendar';
+import '@ilamy/calendar/dist/index.css'; // Import base styles
+
+const MyApp = () => {
+  const events = [
+    {
+      id: '1',
+      title: 'Project Kickoff',
+      start: '2026-05-01T10:00:00Z',
+      end: '2026-05-01T11:30:00Z',
+      color: 'blue'
+    }
+  ];
+
+  return (
+    <div style={{ height: '800px' }}>
+      <IlamyCalendar 
+        events={events}
+        initialView="week"
+        onEventClick={(event) => console.log('Clicked:', event)}
+      />
+    </div>
+  );
+};
+```
+
+---
+
+## Examples
+
+Explore the [examples directory](./examples) for complete implementation patterns:
+
+- [Next.js](./examples/nextjs) - Integration with Next.js and Tailwind CSS.
+- [Astro](./examples/astro) - Static site integration with Astro.
+- [Vite](./examples/vite) - Fast, minimal setup using Vite.
+
+---
 
 ## Documentation
 
-For comprehensive documentation, examples, and interactive demos, visit [ilamy.dev](https://ilamy.dev)
+For comprehensive guides, API references, and interactive demos, visit [ilamy.dev](https://ilamy.dev).
 
-## Code Example
+---
 
-Check out the [examples directory](./examples) for complete project setups:
+## License
 
-- [Next.js Example](./examples/nextjs) - Full-featured Next.js integration
-- [Astro Example](./examples/astro) - Static site integration with Astro
+MIT © [Sujeet Kc](https://github.com/kcsujeet)

package/dist/index.d.ts

@@ -304,6 +304,12 @@ type CalendarView = "month" | "week" | "day" | "year";
 */
 type TimeFormat = "12-hour" | "24-hour";
 /**
+* Granularity of the time grid in minutes for day, week, and resource hour views.
+* Quarter-hour increments only. `60` shows one row per hour with no sub-hour lines.
+* `30` shows two rows per hour. `15` shows four rows per hour with dashed sub-hour separators.
+*/
+type SlotDuration = 15 | 30 | 60;
+/**
 * Custom class names for calendar styling.
 * Allows users to override default styles for various calendar elements.
 */
@@ -360,6 +366,19 @@ interface RenderCurrentTimeIndicatorProps {
 	/** Progress percentage (0-100) representing position in the range */
 	progress: number;
 	/**
+	* Layout axis the indicator is rendered along.
+	* - `'vertical'`: `progress` maps to a `top` offset (day/week vertical grids).
+	* - `'horizontal'`: `progress` maps to a `left` offset (horizontal resource hour grids).
+	*
+	* The library always populates this field, so consumers can treat it as
+	* always defined inside their render function.
+	*
+	* Note: distinct from the `orientation` prop on `IlamyResourceCalendar`.
+	* `orientation` chooses which view component renders the calendar; `axis` tells
+	* your render function which dimension `progress` maps to inside that view.
+	*/
+	axis?: "vertical" | "horizontal";
+	/**
 	* The resource associated with this column (if in a resource-based view).
 	* Pass this to conditionally render custom indicators for specific resources.
 	*/
@@ -538,13 +557,25 @@ interface IlamyCalendarProps {
 	* If provided, replaces the default red line indicator.
 	* Useful for adding custom time labels or styling.
 	*
+	* Branch on `axis` to position correctly across vertical day/week grids
+	* (`axis === 'vertical'` → use `top`) and horizontal resource hour grids
+	* (`axis === 'horizontal'` → use `left`).
+	*
 	* @example
 	* ```tsx
-	* renderCurrentTimeIndicator={({ currentTime, progress, resource, view }) => {
+	* renderCurrentTimeIndicator={({ currentTime, progress, resource, view, axis }) => {
 	*   // Only show the time badge for the first resource in Day view (to avoid repetition)
 	*   const isPrimary = !resource || resource.id === 'room-a'
 	*   const showBadge = view === 'day' ? isPrimary : true
 	*
+	*   if (axis === 'horizontal') {
+	*     return (
+	*       <div style={{ left: `${progress}%` }} className="absolute top-0 bottom-0">
+	*         <div className="w-0.5 h-full bg-red-500" />
+	*       </div>
+	*     )
+	*   }
+	*
 	*   return (
 	*     <div style={{ top: `${progress}%` }} className="absolute left-0 right-0">
 	*       <div className="h-0.5 bg-red-500" />
@@ -583,6 +614,41 @@ interface IlamyCalendarProps {
 	* Receives a Dayjs object for the hour and should return a React node.
 	*/
 	renderHour?: (date: Dayjs) => React3.ReactNode;
+	/**
+	* Granularity of the time grid in minutes for day, week, and resource hour views.
+	* Quarter-hour increments only: `15`, `30`, or `60`.
+	*
+	* - `60` (default): one row per hour, no sub-hour lines.
+	* - `30`: two rows per hour (top of hour, half hour).
+	* - `15`: four rows per hour with dashed sub-hour separators.
+	*
+	* @default 60
+	*/
+	slotDuration?: SlotDuration;
+	/**
+	* Initial scroll position for hour-resolution views (day, week, resource
+	* day, resource week, in both orientations). Accepts `"HH:mm"` or
+	* `"HH:mm:ss"`. Minutes are floored to the hour. The scroll target is
+	* clamped to the nearest visible row when `hideNonBusinessHours` hides
+	* the requested hour.
+	*
+	* Independent of `businessHours`: you can show all 24 hours and still
+	* focus on 08:00 on load.
+	*
+	* **Requires a fixed calendar height** so the internal time grid has a
+	* scroll container to scroll within. If the calendar host element has
+	* `height: auto`, the time grid grows to fit all hours and there is
+	* nothing to scroll — this prop becomes a silent no-op.
+	*
+	* @example
+	* ```tsx
+	* <IlamyCalendar
+	*   businessHours={{ daysOfWeek: [1,2,3,4,5], startTime: 0, endTime: 24 }}
+	*   scrollTime="08:00:00"
+	* />
+	* ```
+	*/
+	scrollTime?: string;
 }
 declare const IlamyCalendar: React4.FC<IlamyCalendarProps>;
 declare const isRecurringEvent: (event: CalendarEvent) => boolean;
@@ -627,4 +693,4 @@ interface UseIlamyCalendarContextReturn {
 */
 declare function useIlamyCalendarContext(): UseIlamyCalendarContextReturn;
 declare const defaultTranslations: Translations;
-export { useIlamyCalendarContext, isRecurringEvent, generateRecurringEvents, defaultTranslations, Weekday, WeekDays, UseIlamyCalendarContextReturn, TranslatorFunction, Translations, TranslationKey, TimeFormat, Resource, RenderCurrentTimeIndicatorProps, RRuleOptions, RRule, IlamyResourceCalendarProps, IlamyResourceCalendar, IlamyCalendarProps, IlamyCalendar, EventFormProps, CellClickInfo, CalendarView, CalendarEvent, BusinessHours };
+export { useIlamyCalendarContext, isRecurringEvent, generateRecurringEvents, defaultTranslations, Weekday, WeekDays, UseIlamyCalendarContextReturn, TranslatorFunction, Translations, TranslationKey, TimeFormat, SlotDuration, Resource, RenderCurrentTimeIndicatorProps, RRuleOptions, RRule, IlamyResourceCalendarProps, IlamyResourceCalendar, IlamyCalendarProps, IlamyCalendar, EventFormProps, CellClickInfo, CalendarView, CalendarEvent, BusinessHours };