Add Airtable-style calendar view component

apps/playground/src/data/examples.ts

@@ -638,6 +638,93 @@ export const examples = {
       ]
     }
   ]
+}`,
+
+  // Calendar View - Airtable-style calendar
+  'calendar-view': `{
+  "type": "div",
+  "className": "space-y-4",
+  "body": [
+    {
+      "type": "div",
+      "className": "space-y-2",
+      "body": [
+        {
+          "type": "text",
+          "content": "Calendar View",
+          "className": "text-2xl font-bold"
+        },
+        {
+          "type": "text",
+          "content": "Airtable-style calendar for displaying records as events",
+          "className": "text-muted-foreground"
+        }
+      ]
+    },
+    {
+      "type": "calendar-view",
+      "className": "h-[600px] border rounded-lg",
+      "view": "month",
+      "titleField": "title",
+      "startDateField": "start",
+      "endDateField": "end",
+      "colorField": "type",
+      "colorMapping": {
+        "meeting": "#3b82f6",
+        "deadline": "#ef4444",
+        "event": "#10b981",
+        "holiday": "#8b5cf6"
+      },
+      "data": [
+        {
+          "id": 1,
+          "title": "Team Standup",
+          "start": "${new Date(new Date().setHours(9, 0, 0, 0)).toISOString()}",
+          "end": "${new Date(new Date().setHours(9, 30, 0, 0)).toISOString()}",
+          "type": "meeting",
+          "allDay": false
+        },
+        {
+          "id": 2,
+          "title": "Project Launch",
+          "start": "${new Date(new Date().setDate(new Date().getDate() + 3)).toISOString()}",
+          "type": "deadline",
+          "allDay": true
+        },
+        {
+          "id": 3,
+          "title": "Client Meeting",
+          "start": "${new Date(new Date().setDate(new Date().getDate() + 5)).toISOString()}",
+          "end": "${new Date(new Date(new Date().setDate(new Date().getDate() + 5)).setHours(14, 0, 0, 0)).toISOString()}",
+          "type": "meeting",
+          "allDay": false
+        },
+        {
+          "id": 4,
+          "title": "Team Building Event",
+          "start": "${new Date(new Date().setDate(new Date().getDate() + 7)).toISOString()}",
+          "end": "${new Date(new Date().setDate(new Date().getDate() + 9)).toISOString()}",
+          "type": "event",
+          "allDay": true
+        },
+        {
+          "id": 5,
+          "title": "Code Review",
+          "start": "${new Date(new Date().setDate(new Date().getDate() + 1)).toISOString()}",
+          "end": "${new Date(new Date(new Date().setDate(new Date().getDate() + 1)).setHours(15, 0, 0, 0)).toISOString()}",
+          "type": "meeting",
+          "allDay": false
+        },
+        {
+          "id": 6,
+          "title": "National Holiday",
+          "start": "${new Date(new Date().setDate(new Date().getDate() + 10)).toISOString()}",
+          "type": "holiday",
+          "allDay": true
+        }
+      ]
+    }
+  ]
 }`
 };
 
@@ -646,5 +733,6 @@ export type ExampleKey = keyof typeof examples;
 export const exampleCategories = {
   'Primitives': ['simple-page', 'input-states', 'button-variants'],
   'Layouts': ['grid-layout', 'dashboard', 'tabs-demo'],
-  'Forms': ['form-demo']
+  'Forms': ['form-demo'],
+  'Data Display': ['calendar-view']
 };

docs/components/calendar-view.md

@@ -0,0 +1,121 @@
+# Calendar View Component
+
+The `calendar-view` component is an Airtable-style calendar for displaying records as events. It provides three view modes: Month, Week, and Day.
+
+## Features
+
+- **Multiple View Modes**: Switch between Month, Week, and Day views
+- **Flexible Data Mapping**: Map your data fields to event properties
+- **Color Coding**: Support for color-coded events with custom color mappings
+- **Interactive**: Click on events and dates (with callbacks)
+- **Responsive**: Works seamlessly on different screen sizes
+
+## Basic Usage
+
+```json
+{
+  "type": "calendar-view",
+  "data": [
+    {
+      "id": 1,
+      "title": "Team Meeting",
+      "start": "2026-01-13T10:00:00.000Z",
+      "end": "2026-01-13T11:00:00.000Z",
+      "color": "#3b82f6"
+    }
+  ]
+}
+```
+
+## Properties
+
+| Property | Type | Default | Description |
+|:---|:---|:---|:---|
+| `data` | `array` | `[]` | Array of record objects to display as events |
+| `view` | `'month' \| 'week' \| 'day'` | `'month'` | Default view mode |
+| `titleField` | `string` | `'title'` | Field name to use for event title |
+| `startDateField` | `string` | `'start'` | Field name for event start date |
+| `endDateField` | `string` | `'end'` | Field name for event end date (optional) |
+| `allDayField` | `string` | `'allDay'` | Field name for all-day flag |
+| `colorField` | `string` | `'color'` | Field name for event color |
+| `colorMapping` | `object` | `{}` | Map field values to colors |
+| `allowCreate` | `boolean` | `false` | Allow creating events by clicking on dates |
+| `className` | `string` | - | Additional CSS classes |
+
+## Data Structure
+
+Each event object in the `data` array should have the following structure:
+
+```typescript
+{
+  id: string | number;           // Unique identifier
+  title: string;                 // Event title (or use custom titleField)
+  start: string | Date;          // Start date/time (ISO string or Date)
+  end?: string | Date;           // End date/time (optional)
+  allDay?: boolean;              // Whether it's an all-day event
+  color?: string;                // Event color (hex or CSS color)
+  [key: string]: any;            // Any other custom data
+}
+```
+
+## Examples
+
+### Month View with Color Mapping
+
+```json
+{
+  "type": "calendar-view",
+  "className": "h-[600px] border rounded-lg",
+  "view": "month",
+  "colorField": "type",
+  "colorMapping": {
+    "meeting": "#3b82f6",
+    "deadline": "#ef4444",
+    "event": "#10b981"
+  },
+  "data": [
+    {
+      "id": 1,
+      "title": "Team Standup",
+      "start": "2026-01-13T09:00:00.000Z",
+      "end": "2026-01-13T09:30:00.000Z",
+      "type": "meeting"
+    },
+    {
+      "id": 2,
+      "title": "Project Deadline",
+      "start": "2026-01-20T00:00:00.000Z",
+      "type": "deadline",
+      "allDay": true
+    }
+  ]
+}
+```
+
+## View Modes
+
+### Month View
+Displays a full month calendar grid with events shown as colored bars on their respective dates. Perfect for getting a high-level overview of the month.
+
+### Week View
+Shows a week at a time with each day in a column. Events display with their times, ideal for detailed weekly planning.
+
+### Day View
+Displays a single day with hourly time slots from 12 AM to 11 PM. Events are positioned at their scheduled times, great for detailed daily schedules.
+
+## Events & Callbacks
+
+The calendar view supports several event callbacks through the `onAction` mechanism:
+
+- `event_click`: Triggered when an event is clicked
+- `date_click`: Triggered when a date cell is clicked
+- `view_change`: Triggered when the view mode changes
+- `navigate`: Triggered when navigating between dates
+
+## Styling
+
+The calendar view is fully styled with Tailwind CSS and supports custom styling through the `className` prop.
+
+## Integration with ObjectQL
+
+When used with ObjectQL, the calendar view can automatically fetch and display records from your database.

docs/spec/component-library.md

@@ -68,6 +68,7 @@ Components for visualizing data.
 | `alert` | Highlighted message | `variant`, `title`, `description` |
 | `table` | Data-driven table | `columns`, `data`, `caption`, `footer` |
 | `carousel` | Slideshow component | `items`, `orientation`, `showArrows` |
+| `calendar-view` | Airtable-style calendar | `data`, `view`, `titleField`, `startDateField`, `endDateField`, `colorField` |
 
 ## 6. Feedback Components
 Indicators for system status or feedback.