@object-ui/plugin-calendar

Calendar view plugins for Object UI - includes both ObjectQL-integrated and standalone calendar components.

Features

• Calendar View - Monthly calendar with event display
• Event Management - Create, edit, and delete events
• Drag-and-Drop Rescheduling - Move events to a different day in month view, or drag vertically in week/day views to change start time. Drag top/bottom edges to resize start/end times. Changes are persisted via dataSource.update() automatically (override with the onEventDrop prop).
• Click-to-Create - Click any day cell (month view) or click-drag on the time grid (week/day views) to open a quick-create dialog pre-filled with the selected date/range. New records are persisted via dataSource.create() and inserted optimistically into the calendar. Required picklist fields auto-default to their first option.
• ObjectQL Integration - Connect to ObjectStack data sources
• Standalone Mode - Use with static data or custom backends
• Responsive - Mobile-friendly calendar layouts
• Customizable - Tailwind CSS styling support

Drag-and-Drop

Month view

| Gesture | Effect | | --- | --- | | Drag the event pill body to another day cell | Shifts both startDateField and endDateField by the day delta. Grab cell → drop cell defines the delta, so dragging from any day of a multi-day span works as expected. | | Drag the right-edge handle of a multi-day pill | Adjusts only endDateField; start is preserved. Refuses drops earlier than start. |

Week / Day view (time grid)

The week and day views render a classic Google Calendar-style vertical time grid with hour rows. Pointer-driven interactions:

| Gesture | Effect | | --- | --- | | Drag an event vertically | Shifts both startDateField and endDateField by the time delta (snapped to slotMinutes, default 30). | | Drag the top edge of an event | Adjusts only startDateField; end is preserved. Refuses to drag past end − slotMinutes. | | Drag the bottom edge of an event | Adjusts only endDateField; start is preserved. Refuses to drag past start + slotMinutes. | | Click-drag on empty grid background | Opens the quick-create dialog with start/end pre-filled to the dragged time range. |

Pass slotMinutes={15} to change the snap granularity. Pass onTimeRangeSelect={(start, end) => …} to handle drag-to-create yourself instead of the default quick-create dialog.

When ObjectCalendar is bound to an object schema, the new dates are persisted with dataSource.update(objectName, id, patch) automatically; the local state is updated optimistically and rolled back if the server call fails. To intercept (e.g. to confirm a status change) pass onEventDrop={(record, newStart, newEnd) => …} — the default persistence is skipped when you provide your own handler.

Click-to-Create

Clicking an empty area of any day cell opens a small quick-create dialog pre-filled with the clicked date. Type a title, press Enter (or click Create), and the record is persisted via dataSource.create(objectName, payload). The payload includes:

• The configured titleField (defaults to name)
• startDateField and (if configured) endDateField set to the clicked day
• Auto-defaults for any other required fields the user hasn't supplied (first picklist option for select/status, false for booleans, 0 for numerics, or the field's defaultValue)

The new record is optimistically inserted into local state so it appears immediately. To override (e.g. open your own create form), pass onDateClick={(day) => …} — the default behaviour is skipped.

Installation

pnpm add @object-ui/plugin-calendar

Usage

Automatic Registration (Side-Effect Import)

// In your app entry point (e.g., App.tsx or main.tsx)
import '@object-ui/plugin-calendar';

// Now you can use calendar types in your schemas
const schema = {
  type: 'calendar-view',
  events: [
    {
      id: '1',
      title: 'Team Meeting',
      start: '2024-01-15T10:00:00',
      end: '2024-01-15T11:00:00'
    }
  ]
};

Manual Registration

import { calendarComponents } from '@object-ui/plugin-calendar';
import { ComponentRegistry } from '@object-ui/core';

// Register calendar components
Object.entries(calendarComponents).forEach(([type, component]) => {
  ComponentRegistry.register(type, component);
});

Schema API

CalendarView

Display a monthly calendar with events:

{
  type: 'calendar-view',
  events?: CalendarEvent[],
  defaultDate?: string,           // ISO date string
  onEventClick?: (event) => void,
  onDateClick?: (date) => void,
  className?: string
}

Calendar Event Structure

interface CalendarEvent {
  id: string;
  title: string;
  start: string;                  // ISO datetime string
  end: string;                    // ISO datetime string
  description?: string;
  color?: string;                 // Tailwind color class
  allDay?: boolean;
}

Examples

Basic Calendar

const schema = {
  type: 'calendar-view',
  events: [
    {
      id: '1',
      title: 'Product Launch',
      start: '2024-02-15T09:00:00',
      end: '2024-02-15T17:00:00',
      color: 'bg-blue-500'
    },
    {
      id: '2',
      title: 'All-Hands Meeting',
      start: '2024-02-20T14:00:00',
      end: '2024-02-20T15:00:00',
      color: 'bg-green-500'
    }
  ]
};

With ObjectQL Integration

const schema = {
  type: 'object-calendar',
  object: 'events',
  titleField: 'name',
  startField: 'startDate',
  endField: 'endDate',
  colorField: 'category.color'
};

Interactive Calendar

const schema = {
  type: 'calendar-view',
  events: [],
  onEventClick: (event) => {
    console.log('Event clicked:', event);
    // Open event details modal
  },
  onDateClick: (date) => {
    console.log('Date clicked:', date);
    // Create new event
  }
};

ObjectQL Integration

When using with ObjectStack, the calendar can automatically fetch and display events:

import { createObjectStackAdapter } from '@object-ui/data-objectstack';

const dataSource = createObjectStackAdapter({
  baseUrl: 'https://api.example.com',
  token: 'your-auth-token'
});

const schema = {
  type: 'object-calendar',
  dataSource,
  object: 'calendar_events',
  fields: {
    title: 'title',
    start: 'start_time',
    end: 'end_time',
    color: 'category_color'
  }
};

Customization

Style the calendar with Tailwind classes:

const schema = {
  type: 'calendar-view',
  className: 'border rounded-lg shadow-lg',
  events: [...]
};

TypeScript Support

import type { CalendarViewSchema, CalendarEvent } from '@object-ui/plugin-calendar';

const event: CalendarEvent = {
  id: '1',
  title: 'Meeting',
  start: '2024-01-15T10:00:00',
  end: '2024-01-15T11:00:00'
};

const schema: CalendarViewSchema = {
  type: 'calendar-view',
  events: [event]
};

Compatibility

• React: 18.x or 19.x
• Node.js: ≥ 18
• TypeScript: ≥ 5.0 (strict mode)
• @objectstack/spec: ^3.3.0
• @objectstack/client: ^3.3.0
• Tailwind CSS: ≥ 3.4 (for packages with UI)

Links

• 📚 Documentation
• 📦 npm package
• 📝 Changelog
• 🐛 Report an issue
• 🤝 Contributing Guide
• 🗺️ Roadmap

License

MIT — see LICENSE.