CalSync Documentation

import { CalendarApp } from "@calsync-react/calendar";
import "@calsync-react/calendar/styles.css";

function App() {
  return (
    <div className="h-screen w-screen">
      <CalendarApp
        locale="en"
        preventOverlap={true}
        defaultView="month"
        licenseKey="YOUR_LICENSE_KEY"
      />
    </div>
  );
}

// Set initial view
<CalendarApp defaultView="week" />

// Set initial view + initial date
<CalendarApp
  defaultView="day"
  defaultDate={new Date(2025, 5, 15)} // June 15, 2025
/>

<CalendarApp
  onEventCreate={(event) => {
    console.log("New event:", event);
    // event has: id, title, description, start, end, type, location, agendaId
    await api.events.create(event);
  }}
/>

<CalendarApp
  onEventUpdate={(event) => {
    // Fires on: modal save, drag-move, resize
    await api.events.update(event.id, event);
  }}
  onEventClick={(event) => {
    // Fires before the edit modal opens
    analytics.track("event_clicked", { id: event.id });
  }}
/>

<CalendarApp
  onEventDelete={(eventId) => {
    await api.events.delete(eventId);
  }}
/>

// CalSync manages agendas internally
<CalendarApp locale="en" />

const [agendas, setAgendas] = useState<Agenda[]>([
  {
    id: "1",
    name: "Team Alpha",
    color: "#3b82f6",
    isActive: true,
    eventCount: 0,
    createdAt: new Date(),
  },
  {
    id: "2",
    name: "Team Beta",
    color: "#10b981",
    isActive: true,
    eventCount: 0,
    createdAt: new Date(),
  },
]);

<CalendarApp
  agendas={agendas}
  onAgendaCreate={(agenda) => {
    setAgendas((prev) => [...prev, agenda]);
  }}
  onAgendaDelete={(agendaId) => {
    setAgendas((prev) => prev.filter((a) => a.id !== agendaId));
  }}
/>

<CalendarApp
  preventOverlap={true}   // block overlapping events (default)
  onEventUpdate={(event) => {
    // Fires after drag-move or resize completes
    console.log(`Event ${event.id} moved to ${event.start}`);
  }}
/>

// Allow overlapping events
<CalendarApp preventOverlap={false} />

<CalendarApp
  onAvailabilityChange={(rules) => {
    console.log("Updated rules:", rules);
    // Save to your backend
    await api.availability.save(rules);
  }}
/>

import type { AvailabilityRule } from "@calsync-react/calendar";

const [rules, setRules] = useState<AvailabilityRule[]>([
  {
    id: "office-hours",
    label: "Office Hours",
    days: [1, 2, 3, 4, 5],   // Mon–Fri
    startHour: 9,
    endHour: 17,
    color: "bg-green-300",
  },
  {
    id: "saturday-morning",
    label: "Saturday Morning",
    days: [6],                // Saturday
    startHour: 10,
    endHour: 13,
    color: "bg-blue-300",
  },
]);

<CalendarApp
  availabilityRules={rules}
  onAvailabilityChange={(updated) => setRules(updated)}
/>

import type { CalendarEvent, RecurrenceRule } from "@calsync-react/calendar";

const weeklyMeeting: CalendarEvent = {
  id: "weekly-standup",
  title: "Team Standup",
  description: "Daily sync",
  start: new Date(2025, 5, 16, 9, 0),
  end: new Date(2025, 5, 16, 9, 30),
  type: "Meeting",
  recurrence: {
    frequency: "weekly",
    interval: 1,
    byDay: [1, 3, 5],  // Mon, Wed, Fri
    count: 52,          // 1 year of weekly meetings
  },
};

// Use browser timezone (default)
<CalendarApp />

// Force a specific timezone
<CalendarApp timezone="America/New_York" />
<CalendarApp timezone="Europe/London" />
<CalendarApp timezone="Asia/Tokyo" />

import { useState } from "react";
import { CalendarApp } from "@calsync-react/calendar";
import type { CalendarEvent, ViewType } from "@calsync-react/calendar";

function App() {
  const [events, setEvents] = useState<CalendarEvent[]>([]);
  const [view, setView] = useState<ViewType>("month");

  return (
    <CalendarApp
      events={events}
      defaultView={view}
      licenseKey="YOUR_LICENSE_KEY"
      onEventCreate={(e) => {
        setEvents((prev) => [...prev, e]);
        // save to your DB here
      }}
      onEventUpdate={(e) => {
        setEvents((prev) => prev.map((x) => (x.id === e.id ? e : x)));
      }}
      onEventDelete={(id) => {
        setEvents((prev) => prev.filter((x) => x.id !== id));
      }}
      onViewChange={(v) => setView(v)}
    />
  );
}

<CalendarApp
  licenseKey="CALSYNC-XXXX-XXXX-XXXX"
  locale="en"
  defaultView="week"
  // Event callbacks
  onEventCreate={(event) => api.events.create(event)}
  onEventUpdate={(event) => api.events.update(event.id, event)}
  onEventDelete={(id) => api.events.delete(id)}
  onEventClick={(event) => console.log("Clicked:", event.title)}
  // Agenda callbacks
  onAgendaCreate={(agenda) => api.agendas.create(agenda)}
  onAgendaDelete={(id) => api.agendas.delete(id)}
  // Navigation callbacks
  onViewChange={(view) => router.push(`?view=${view}`)}
  onDateChange={(date) => router.push(`?date=${date.toISOString()}`)}
/>

// Show only business hours (8 AM – 6 PM)
<CalendarApp
  defaultSettings={{ startHour: 8, endHour: 18 }}
  defaultView="week"
/>

// Morning clinic (6 AM – 1 PM)
<CalendarApp
  defaultSettings={{ startHour: 6, endHour: 13 }}
  defaultView="day"
/>

# .env.local
NEXT_PUBLIC_CALSYNC_KEY=CALSYNC-XXXX-XXXX-XXXX

<CalendarApp
  licenseKey={process.env.NEXT_PUBLIC_CALSYNC_KEY}
/>

import { CalendarApp } from "@calsync-react/calendar";
import type { CalendarEvent, Agenda, ViewType } from "@calsync-react/calendar";

function MyCalendar() {
  const [events, setEvents] = useState<CalendarEvent[]>([]);
  const [agendas, setAgendas] = useState<Agenda[]>([]);
  const [view, setView] = useState<ViewType>("week");
  const [date, setDate] = useState(new Date());

  return (
    <CalendarApp
      // License
      licenseKey={process.env.NEXT_PUBLIC_CALSYNC_KEY}
      // Appearance
      locale="en"
      defaultView={view}
      defaultDate={date}
      defaultSettings={{ startHour: 7, endHour: 20 }}
      // Behaviour
      preventOverlap={true}
      // Controlled data
      events={events}
      agendas={agendas}
      // Event callbacks
      onEventCreate={(e) => setEvents((p) => [...p, e])}
      onEventUpdate={(e) => setEvents((p) => p.map((x) => x.id === e.id ? e : x))}
      onEventDelete={(id) => setEvents((p) => p.filter((x) => x.id !== id))}
      // Agenda callbacks
      onAgendaCreate={(a) => setAgendas((p) => [...p, a])}
      onAgendaDelete={(id) => setAgendas((p) => p.filter((x) => x.id !== id))}
      // Navigation callbacks
      onViewChange={setView}
      onDateChange={setDate}
    />
  );
}

type CalendarEvent = {
  id: string;
  title: string;
  description: string;
  start: Date;
  end: Date;
  type: string;
  location?: string;
  agendaId?: string;
  customData?: Record<string, string | number | boolean>;
  recurrence?: RecurrenceRule;
  timezone?: string;
};

type AvailabilityRuleDay = 0 | 1 | 2 | 3 | 4 | 5 | 6; // Sun=0 … Sat=6

type AvailabilityRule = {
  id: string;
  label: string;
  days: AvailabilityRuleDay[];
  startHour: number;   // 0–23 (decimals for half-hours, e.g. 9.5 = 9:30)
  endHour: number;
  color: string;       // Tailwind bg class, e.g. "bg-green-300"
};

type RecurrenceFrequency = "daily" | "weekly" | "monthly" | "yearly";

type RecurrenceRule = {
  frequency: RecurrenceFrequency;
  interval?: number;        // Every N days/weeks/months/years (default 1)
  byDay?: number[];         // For weekly: days of week (0=Sun … 6=Sat)
  count?: number;           // Stop after N occurrences
  until?: string;           // Stop on this date (ISO string)
};

type CustomFieldType = "text" | "number" | "select" | "textarea" | "checkbox" | "date" | "time";

interface CustomField {
  name: string;        // Unique key used in customData
  label: string;       // Display label
  type: CustomFieldType;
  required?: boolean;
  placeholder?: string;
  defaultValue?: string | number | boolean;
  options?: { label: string; value: string }[];  // For "select" type
}

<CalendarApp
  licenseKey="YOUR_KEY"
  customFields={[
    { name: "patient", label: "Patient Name", type: "text", required: true, placeholder: "Enter patient name" },
    { name: "room", label: "Room", type: "select", options: [
      { label: "Room A", value: "a" },
      { label: "Room B", value: "b" },
    ]},
    { name: "notes", label: "Notes", type: "textarea", placeholder: "Additional notes..." },
    { name: "urgent", label: "Urgent", type: "checkbox" },
  ]}
  onEventCreate={(event) => {
    console.log(event.customData);
    // { patient: "John Doe", room: "a", notes: "...", urgent: true }
  }}
/>

type Agenda = {
  id: string;
  name: string;
  color: string;
  isActive: boolean;
  eventCount: number;
  createdAt: Date;
};

type ViewType = "month" | "week" | "day" | "year" | "agenda";

<CalendarApp locale="en" />  // English
<CalendarApp locale="fr" />  // French (default)
<CalendarApp locale="ja" />  // Japanese

<CalendarApp
  licenseKey="CALSYNC-XXXX-XXXX-XXXX-XXXX"
  locale="en"
  defaultView="month"
/>