Calendars

The calendar component — a month, week or day view of date-bearing records.

A calendar places each record on the date its dateField names. The field mappings sit at the top level; only click handling and the time-grid settings live under calendarEvent and calendarInteraction.

dataSource

autoSave

search

calendarEvent

calendarInteraction

dateField supplies each event's start and endDateField its end, for events that span time. labelField is rendered as the event's label, and defaultView is month, week or day. maxEventsPerDay caps a day cell before it collapses into a "+N more" affordance.

calendarEvent.onEventClick runs when an event is clicked and calendarInteraction.onDateClick when an empty date or slot is. calendarInteraction.timeSlotInterval is the slot length in minutes for week and day views, and showCurrentTimeIndicator draws a line at the current time.

tables:
  - name: bookings
    fields:
      - { name: customer_name, type: single-line-text }
      - { name: starts_at, type: datetime }
      - { name: ends_at, type: datetime }
pages:
  - name: Bookings
    path: /bookings
    components:
      - type: calendar
        dataSource: { table: bookings }
        dateField: starts_at
        endDateField: ends_at
        labelField: customer_name
        defaultView: week
        calendarInteraction: { timeSlotInterval: 30, showCurrentTimeIndicator: true }

A coloured event is a block, not a dot

A calendar reads colorField at the top level — the record-view colour rules are the same ones a kanban board follows, including where the hue comes from and what happens when a value declares none.

In month view a calendar renders a timed event as a small dot by default. A dot is mostly empty space, so a colour applied to it is close to invisible. An event that carries a colour therefore renders as a filled block instead; an event with no colour keeps the default dot.

Expect that as a visible layout change on any month-view calendar that sets colorField — day cells that used to hold lines of dots now hold bands of filled blocks.

Behaviour

Data Calendar

• type: 'calendar' is a valid component type in page components
• dataSource.table binds the calendar to a table
• dateField maps a record's date/datetime field to calendar position
• endDateField enables multi-day events spanning across cells
• defaultView sets the initial view mode (month, week, day)
• Navigation buttons (previous, next, today) change the visible period
• labelField renders the record field value as the event label
• colorField maps field values to event background colors
• Multi-day events span across date cells from dateField to endDateField
• maxEventsPerDay limits visible events with a "+N more" overflow
• onEventClick triggers a navigation or modal action on event click
• onDateClick triggers a create action with the clicked date pre-filled
• Dragging an event to a different date updates the dateField
• Week/day views show time slots based on timeSlotInterval
• showCurrentTimeIndicator renders a line at the current time
• The week and day views render rather than throwing on a slot duration
• A timed view honours the slot interval and the now-indicator
• User can complete full calendar workflow end-to-end (regression)

System read-endpoint data source

• A system-source calendar whose dateField/labelField are NOT app.tables fields boots successfully (field cross-validation is skipped)
• With dataSource.system, the calendar fetches system.endpoint and never falls through to /api/tables/:t/records
• The { items: [...] } envelope is normalized to calendar events; total falls back to rows length when totalKey is absent
• dateField positions and labelField labels each event against endpoint rows (config drives rendering, not a table schema)
• dataSource.system.query static params are merged into the endpoint request
• A system-source calendar offers no record-write affordances (no drag-to-reschedule, no onDateClick create, no event edit)
• A system-source calendar offers no saved/user views and no user-preferences (read-only, endpoint-shaped)
• View switching (month/week/day) stays ON for a system source — a read-side control that re-reads the endpoint, never the records API
• The existing dataSource.table binding still positions table rows on the date grid unchanged (discriminated-union regression)
• A system-source calendar validates, fetches its endpoint, normalizes the envelope into events, gates writes off, keeps view switching, leaves DB intact