beautify-event 1.0.0

package/README.md

@@ -0,0 +1,382 @@
+# Beautify Event
+
+A beautiful, fully customizable React event calendar component with month, week, day, 2-day, and resource views. Built with Radix UI, Tailwind CSS, and date-fns.
+
+## Features
+
+- **Multiple Views**: Month, Week, Day, 2-Day, and Resource views
+- **Responsive**: Mobile-optimized with collapsible month picker and horizontal-scrolling week view
+- **Localization**: Built-in support for English, French, and Arabic (extensible)
+- **Drag & Drop**: Create events by dragging on empty slots; move events by dragging
+- **Current Time Line**: Optional horizontal line showing the current time in day/week views
+- **Customizable**: Custom event renderers, headers, themes, and styling
+- **TypeScript**: Full type definitions included
+
+## Installation
+
+```bash
+npm install beautify-event
+```
+
+### Peer Dependencies
+
+Beautify Event requires the following peer dependencies. Install them if not already present:
+
+```bash
+npm install react react-dom date-fns
+```
+
+For full styling and component support, you'll also need:
+
+- **Tailwind CSS** (v3 or v4)
+- **Radix UI** primitives (or shadcn/ui)
+- **lucide-react** (or ensure icons are available)
+
+## Quick Start
+
+```tsx
+import { EventCalendar } from "beautify-event"
+import type { CalendarEvent } from "beautify-event"
+
+const events: CalendarEvent[] = [
+  {
+    id: "1",
+    title: "Team Meeting",
+    start: new Date(2026, 2, 10, 9, 0),
+    end: new Date(2026, 2, 10, 10, 0),
+    color: "#3b82f6",
+  },
+]
+
+export default function App() {
+  return (
+    <div className="h-[600px]">
+      <EventCalendar events={events} />
+    </div>
+  )
+}
+```
+
+## Usage
+
+### Basic Example
+
+```tsx
+<EventCalendar
+  events={events}
+  defaultDate={new Date()}
+  defaultView="week"
+  views={["month", "week", "day"]}
+/>
+```
+
+### Controlled Mode
+
+```tsx
+const [date, setDate] = useState(new Date())
+const [view, setView] = useState<ViewType>("week")
+
+<EventCalendar
+  events={events}
+  date={date}
+  view={view}
+  onDateChange={setDate}
+  onViewChange={setView}
+/>
+```
+
+### With Resources (Rooms, etc.)
+
+```tsx
+const resources: Resource[] = [
+  { id: "room-1", name: "Conference Room A", color: "#3b82f6" },
+  { id: "room-2", name: "Meeting Room B", color: "#10b981" },
+]
+
+<EventCalendar
+  events={events}
+  resources={resources}
+  views={["month", "week", "day", "resource"]}
+/>
+```
+
+### Event Handlers
+
+```tsx
+<EventCalendar
+  events={events}
+  onEventClick={(event) => console.log("Clicked:", event)}
+  onEventDoubleClick={(event) => openEditModal(event)}
+  onSlotClick={(slot) => createEvent(slot)}
+  onSlotDoubleClick={(slot) => createEvent(slot)}
+  onDayClick={(date) => navigateToDay(date)}
+  onDateChange={(date) => setSelectedDate(date)}
+  onRangeChange={(range) => fetchEvents(range)}
+/>
+```
+
+### Drag & Drop
+
+```tsx
+<EventCalendar
+  events={events}
+  enableDragToCreate
+  enableDragToMove
+  onEventCreate={(slotInfo) => {
+    const newEvent = { id: "new-1", title: "New Event", ...slotInfo }
+    setEvents((prev) => [...prev, newEvent])
+  }}
+  onEventMove={({ event, newStart, newEnd }) => {
+    setEvents((prev) =>
+      prev.map((e) =>
+        e.id === event.id ? { ...e, start: newStart, end: newEnd } : e
+      )
+    )
+  }}
+/>
+```
+
+## Calendar Options
+
+Pass configuration via `calendarOptions`:
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `startHour` | `number` | `0` | Start hour for time series (0-23) |
+| `endHour` | `number` | `24` | End hour (use 24 for full day) |
+| `timeFormat` | `"12h" \| "24h"` | `"12h"` | Hour label format |
+| `weekStartsOn` | `0-6` | `0` | First day of week (0 = Sunday) |
+| `hourHeight` | `number` | `64` | Height of each hour slot in pixels |
+| `timeSeriesMaxHeight` | `number \| string` | `400` | Max height for day/week grid; enables scrolling |
+| `showCurrentTimeLine` | `boolean` | `true` | Show horizontal line at current time |
+| `maxEventsPerDay` | `number` | `3` | Events to show before "+X more" in month view |
+| `defaultEventColor` | `string` | `"#3b82f6"` | Default event color |
+| `defaultResourceColor` | `string` | `"#6366f1"` | Default resource color |
+| `locale` | `string` | `"en-US"` | Locale for formatting |
+
+```tsx
+<EventCalendar
+  events={events}
+  calendarOptions={{
+    startHour: 8,
+    endHour: 20,
+    timeFormat: "24h",
+    weekStartsOn: 1,
+    locale: "fr",
+    timeSeriesMaxHeight: 500,
+    showCurrentTimeLine: true,
+  }}
+/>
+```
+
+## Localization
+
+Built-in locales: **English** (`en`, `en-US`), **French** (`fr`), **Arabic** (`ar`).
+
+```tsx
+<EventCalendar
+  events={events}
+  calendarOptions={{ locale: "fr" }}
+/>
+```
+
+To integrate with your app's i18n:
+
+```tsx
+// With next-intl
+const locale = useLocale()
+
+// With react-i18next
+const { i18n } = useTranslation()
+
+<EventCalendar
+  events={events}
+  calendarOptions={{ locale: i18n.language }}
+/>
+```
+
+## Themes
+
+```tsx
+// Use system/app theme
+<EventCalendar events={events} />
+
+// Force light or dark
+<EventCalendar events={events} theme="dark" />
+
+// Custom theme variables
+<EventCalendar
+  events={events}
+  themeVars={{
+    "--primary": "#6366f1",
+    "--background": "#0f172a",
+    "--foreground": "#f8fafc",
+  }}
+/>
+```
+
+## Props Reference
+
+### EventCalendar
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `events` | `CalendarEvent[]` | **required** | Events to display |
+| `resources` | `Resource[]` | `[]` | Resources for resource view |
+| `date` | `Date` | - | Controlled current date |
+| `defaultDate` | `Date` | `new Date()` | Initial date (uncontrolled) |
+| `view` | `ViewType` | - | Controlled view |
+| `defaultView` | `ViewType` | `"month"` | Initial view (uncontrolled) |
+| `views` | `ViewType[]` | `["month","week","day","resource"]` | Available views |
+| `calendarOptions` | `CalendarOptions` | `{}` | Calendar configuration |
+| `showNavigation` | `boolean` | `true` | Show prev/next buttons |
+| `showViewSwitcher` | `boolean` | `true` | Show view toggle |
+| `showTodayButton` | `boolean` | `true` | Show Today button |
+| `className` | `string` | - | Container class name |
+| `loading` | `boolean` | `false` | Loading state |
+| `theme` | `"light" \| "dark" \| "system"` | `"system"` | Theme mode |
+| `themeVars` | `Record<string, string>` | - | CSS variable overrides |
+| `enableDragToCreate` | `boolean` | `false` | Allow drag to create events |
+| `enableDragToMove` | `boolean` | `false` | Allow drag to move events |
+| `mobileBreakpoint` | `"sm" \| "md" \| "lg"` | `"md"` | Breakpoint for mobile layout |
+| `showMobileMonthPicker` | `boolean` | `true` | Show month picker on mobile |
+
+### CalendarEvent
+
+```ts
+interface CalendarEvent {
+  id: string
+  title: string
+  start: Date
+  end: Date
+  color?: string
+  resourceId?: string
+  description?: string
+  allDay?: boolean
+}
+```
+
+### Resource
+
+```ts
+interface Resource {
+  id: string
+  name: string
+  color?: string
+}
+```
+
+## Custom Renderers
+
+### Custom Event Content
+
+```tsx
+<EventCalendar
+  events={events}
+  renderEvent={(event, view) => (
+    <div className="custom-event">
+      <strong>{event.title}</strong>
+      {event.description && <p>{event.description}</p>}
+    </div>
+  )}
+/>
+```
+
+### Custom Header
+
+```tsx
+<EventCalendar
+  events={events}
+  renderHeader={({ date, view, title, onNavigate, onToday }) => (
+    <div className="flex items-center justify-between">
+      <h1>{title}</h1>
+      <div>
+        <button onClick={() => onNavigate("prev")}>Prev</button>
+        <button onClick={onToday}>Today</button>
+        <button onClick={() => onNavigate("next")}>Next</button>
+      </div>
+    </div>
+  )}
+/>
+```
+
+### Selected Event / Slot UI
+
+```tsx
+<EventCalendar
+  events={events}
+  renderSelectedEvent={({ event, onClose }) =>
+    event && (
+      <Sheet open={!!event} onOpenChange={(open) => !open && onClose()}>
+        <SheetContent>
+          <SheetHeader>
+            <SheetTitle>{event.title}</SheetTitle>
+          </SheetHeader>
+          <p>{event.description}</p>
+        </SheetContent>
+      </Sheet>
+    )
+  }
+  renderSelectedSlot={({ slot, onClose }) => (
+    // Your slot detail UI
+  )}
+/>
+```
+
+## Mobile Behavior
+
+On viewports below the `mobileBreakpoint`:
+
+- Simplified header with week strip
+- Month title with expandable month picker (chevron toggle)
+- Week view shows ~2 days at a time with horizontal scroll
+- Sticky time labels column during horizontal scroll
+- Touch-friendly day selection
+
+## Exports
+
+```ts
+// Components
+export { EventCalendar, EventCalendarThemeProvider, useCalendar }
+
+// Types
+export type {
+  ViewType,
+  TimeFormat,
+  CalendarOptions,
+  CalendarEvent,
+  Resource,
+  SlotInfo,
+  DateRange,
+  EventCalendarProps,
+  HeaderRenderProps,
+  CalendarConfig,
+  CalendarTheme,
+}
+
+// Utilities
+export {
+  getMonthDays,
+  getWeekDays,
+  getEventsForDay,
+  navigateDate,
+  getViewTitle,
+  getViewDateRange,
+  formatHour,
+  formatDate,
+  getDateFnsLocale,
+  getHoursArray,
+  createSlotDate,
+}
+```
+
+## Requirements
+
+- React 18+
+- Tailwind CSS
+- Radix UI (or shadcn/ui components)
+- date-fns
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,217 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as React$1 from 'react';
+import { Locale } from 'date-fns';
+
+type ViewType = "month" | "week" | "day" | "2day" | "resource";
+type TimeFormat = "12h" | "24h";
+interface CalendarOptions {
+    /** Start hour for time series in day/week/resource views (0-23). Default: 0 (12:00 AM) */
+    startHour?: number;
+    /** End hour for time series (0-24). Use 24 for full day. Default: 24 (11:59 PM) */
+    endHour?: number;
+    /** Time format for hour labels: "12h" (12 AM/PM) or "24h" (00:00-23:00). Default: "12h" */
+    timeFormat?: TimeFormat;
+    /** First day of week (0 = Sunday, 1 = Monday, etc.) */
+    weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
+    /** Height of each hour slot in pixels */
+    hourHeight?: number;
+    /** Max height for the time series grid (day/week views). Enables scrolling. Default: "400px" */
+    timeSeriesMaxHeight?: number | string;
+    /** Show a horizontal line at the current time in day/week views. Default: true */
+    showCurrentTimeLine?: boolean;
+    /** Number of events to show before "+X more" in month view */
+    maxEventsPerDay?: number;
+    /** Default event color if not specified on event */
+    defaultEventColor?: string;
+    /** Default resource color if not specified on resource */
+    defaultResourceColor?: string;
+    /** Locale for date formatting. Built-in: "en", "en-US", "fr", "ar" */
+    locale?: string;
+}
+interface Resource {
+    id: string;
+    name: string;
+    color?: string;
+    [key: string]: unknown;
+}
+interface CalendarEvent {
+    id: string;
+    title: string;
+    start: Date;
+    end: Date;
+    color?: string;
+    resourceId?: string;
+    description?: string;
+    allDay?: boolean;
+    [key: string]: unknown;
+}
+interface DateRange {
+    start: Date;
+    end: Date;
+}
+interface SlotInfo {
+    start: Date;
+    end: Date;
+    resourceId?: string;
+}
+interface EventCalendarProps {
+    /** Array of events to display */
+    events: CalendarEvent[];
+    /** Array of resources for resource view */
+    resources?: Resource[];
+    /** Currently selected date (controlled) */
+    date?: Date;
+    /** Default date when uncontrolled */
+    defaultDate?: Date;
+    /** Current view type (controlled) */
+    view?: ViewType;
+    /** Default view when uncontrolled */
+    defaultView?: ViewType;
+    /** Available views to show in the header */
+    views?: ViewType[];
+    /** Calendar configuration options */
+    calendarOptions?: CalendarOptions;
+    /** Whether to show navigation controls */
+    showNavigation?: boolean;
+    /** Whether to show view switcher */
+    showViewSwitcher?: boolean;
+    /** Whether to show today button */
+    showTodayButton?: boolean;
+    /** Custom class name for the container */
+    className?: string;
+    /** Loading state */
+    loading?: boolean;
+    /** Theme: "light" | "dark" | "system". When set, calendar uses its own theme scope. Default: "system" */
+    theme?: "light" | "dark" | "system";
+    /** Custom theme variables. Override CSS vars: e.g. { "--background": "#fff", "--primary": "#3b82f6" } */
+    themeVars?: Record<string, string>;
+    /** Enable drag on empty slot to create event. Default: false */
+    enableDragToCreate?: boolean;
+    /** Enable drag event to move. Default: false */
+    enableDragToMove?: boolean;
+    /** Breakpoint for mobile layout: "sm" | "md" | "lg". Default: "md" (768px) */
+    mobileBreakpoint?: "sm" | "md" | "lg";
+    /** Whether to show mini month picker on mobile. Default: true */
+    showMobileMonthPicker?: boolean;
+    /** Called when an event is clicked */
+    onEventClick?: (event: CalendarEvent) => void;
+    /** Called when an event is double clicked */
+    onEventDoubleClick?: (event: CalendarEvent) => void;
+    /** Called when a slot is clicked (for creating new events) */
+    onSlotClick?: (slotInfo: SlotInfo) => void;
+    /** Called when a slot is double clicked */
+    onSlotDoubleClick?: (slotInfo: SlotInfo) => void;
+    /** Called when the date changes */
+    onDateChange?: (date: Date) => void;
+    /** Called when the view changes */
+    onViewChange?: (view: ViewType) => void;
+    /** Called when navigating (prev/next/today) */
+    onNavigate?: (date: Date, action: "prev" | "next" | "today") => void;
+    /** Called when visible date range changes */
+    onRangeChange?: (range: DateRange) => void;
+    /** Called when a day is clicked in month view */
+    onDayClick?: (date: Date) => void;
+    /** Called when event is created via drag (enableDragToCreate) */
+    onEventCreate?: (slotInfo: SlotInfo) => void;
+    /** Called when event is moved via drag (enableDragToMove) */
+    onEventMove?: (params: {
+        event: CalendarEvent;
+        newStart: Date;
+        newEnd: Date;
+        resourceId?: string;
+    }) => void;
+    /** Custom event renderer */
+    renderEvent?: (event: CalendarEvent, view: ViewType) => React.ReactNode;
+    /** Custom day cell renderer for month view */
+    renderDayCell?: (date: Date, events: CalendarEvent[]) => React.ReactNode;
+    /** Custom header renderer */
+    renderHeader?: (props: HeaderRenderProps) => React.ReactNode;
+    /** Custom resource header renderer */
+    renderResourceHeader?: (resource: Resource) => React.ReactNode;
+    /** Custom time slot label renderer */
+    renderTimeSlot?: (hour: number) => React.ReactNode;
+    /** Custom empty state renderer */
+    renderEmpty?: () => React.ReactNode;
+    /** Render selected event UI (drawer, popover, modal, etc.). Receives event (null when closed) and onClose. */
+    renderSelectedEvent?: (props: {
+        event: CalendarEvent | null;
+        onClose: () => void;
+    }) => React.ReactNode;
+    /** Render selected slot UI (drawer, popover, modal, etc.). Receives slot (null when closed) and onClose. */
+    renderSelectedSlot?: (props: {
+        slot: SlotInfo | null;
+        onClose: () => void;
+    }) => React.ReactNode;
+}
+interface HeaderRenderProps {
+    date: Date;
+    view: ViewType;
+    onNavigate: (direction: "prev" | "next") => void;
+    onViewChange: (view: ViewType) => void;
+    onToday: () => void;
+    title: string;
+    views: ViewType[];
+}
+interface CalendarContextValue {
+    currentDate: Date;
+    view: ViewType;
+    events: CalendarEvent[];
+    resources: Resource[];
+    config: CalendarConfig;
+    onEventClick?: (event: CalendarEvent) => void;
+    onEventDoubleClick?: (event: CalendarEvent) => void;
+    onSlotClick?: (slotInfo: SlotInfo) => void;
+    onSlotDoubleClick?: (slotInfo: SlotInfo) => void;
+    onDayClick?: (date: Date) => void;
+    renderEvent?: (event: CalendarEvent, view: ViewType) => React.ReactNode;
+    enableDragToCreate?: boolean;
+    enableDragToMove?: boolean;
+    onEventCreate?: (slotInfo: SlotInfo) => void;
+    onEventMove?: (params: {
+        event: CalendarEvent;
+        newStart: Date;
+        newEnd: Date;
+        resourceId?: string;
+    }) => void;
+}
+interface CalendarConfig {
+    weekStartsOn: 0 | 1 | 2 | 3 | 4 | 5 | 6;
+    startHour: number;
+    endHour: number;
+    hourHeight: number;
+    maxEventsPerDay: number;
+    timeSeriesMaxHeight?: number | string;
+    showCurrentTimeLine?: boolean;
+    defaultEventColor: string;
+    defaultResourceColor: string;
+    locale: string;
+    timeFormat: TimeFormat;
+}
+
+declare function EventCalendar({ events, resources, date, defaultDate, view, defaultView, views, calendarOptions, showNavigation, showViewSwitcher, showTodayButton, className, loading, theme, themeVars, enableDragToCreate, enableDragToMove, mobileBreakpoint, showMobileMonthPicker, onEventClick, onEventDoubleClick, onSlotClick, onSlotDoubleClick, onDateChange, onViewChange, onNavigate, onRangeChange, onDayClick, onEventCreate, onEventMove, renderEvent, renderDayCell, renderHeader, renderResourceHeader, renderTimeSlot, renderEmpty, renderSelectedEvent, renderSelectedSlot, }: EventCalendarProps): react_jsx_runtime.JSX.Element;
+
+type CalendarTheme = "light" | "dark" | "system";
+interface EventCalendarThemeProviderProps {
+    theme?: CalendarTheme;
+    /** Custom CSS variable overrides. Keys with or without -- prefix work. */
+    themeVars?: Record<string, string>;
+    children: React$1.ReactNode;
+}
+declare function EventCalendarThemeProvider({ theme, themeVars, children, }: EventCalendarThemeProviderProps): react_jsx_runtime.JSX.Element;
+
+declare function useCalendar(): CalendarContextValue;
+
+declare function getDateFnsLocale(localeCode: string): Locale;
+/** Format date with locale support */
+declare function formatDate(date: Date, formatStr: string, localeCode?: string): string;
+declare function getMonthDays(date: Date, weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6): Date[];
+declare function getWeekDays(date: Date, weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6): Date[];
+declare function getEventsForDay(events: CalendarEvent[], day: Date): CalendarEvent[];
+declare function navigateDate(date: Date, view: ViewType, direction: "prev" | "next"): Date;
+declare function getViewTitle(date: Date, view: ViewType, weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6, localeCode?: string): string;
+declare function getViewDateRange(date: Date, view: ViewType, weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6): DateRange;
+declare function createSlotDate(day: Date, hour: number, minute?: number): Date;
+declare function getHoursArray(startHour?: number, endHour?: number): number[];
+declare function formatHour(hour: number, timeFormat?: TimeFormat, localeCode?: string): string;
+
+export { type CalendarConfig, type CalendarEvent, type CalendarOptions, type CalendarTheme, type DateRange, EventCalendar, type EventCalendarProps, EventCalendarThemeProvider, type HeaderRenderProps, type Resource, type SlotInfo, type TimeFormat, type ViewType, createSlotDate, formatDate, formatHour, getDateFnsLocale, getEventsForDay, getHoursArray, getMonthDays, getViewDateRange, getViewTitle, getWeekDays, navigateDate, useCalendar };