useDocyrusCalendar

Installation

pnpm dlx @docyrus/cli add @docyrus/hooks-use-docyrus-calendar

pnpm add @docyrus/app-utils @docyrus/api-client @tanstack/react-query

This hook is distributed as source. It expects an authenticated RestApiClient from @docyrus/api-client and a QueryClientProvider from @tanstack/react-query somewhere above your component tree.

Overview

useDocyrusCalendar is the calendar-first companion to useDocyrusDataGrid. It maps a Docyrus data source to the Calendar component without forcing you to hand-build the event transformation:

• loads the active Docyrus data source metadata
• auto-detects the date / end-date / title / color / description / user fields, or uses the slugs you provide
• keeps saved-view filtering, sorting, and search wiring from useDocyrusDataGrid
• requests only the columns the calendar actually needs
• transforms records into IEvent objects ready for CalendarProvider
• wires create / update / delete / drag-and-drop callbacks to the Docyrus REST endpoints
• optionally narrows the items query to records overlapping the calendar's visible range

The hook returns a ready-to-spread calendarProviderProps object so the page code stays small.

Usage

Minimal page

'use client';

import { useDocyrusAuth } from '@docyrus/signin';

import {
  Calendar,
  CalendarProvider
} from '@docyrus/ui/components/calendar';
import { useDocyrusCalendar } from '@docyrus/ui/library/hooks/use-docyrus-calendar';

export function MeetingsCalendarPage() {
  const { client } = useDocyrusAuth();

  if (!client) return null;

  const calendar = useDocyrusCalendar({
    client,
    appSlug: 'base',
    dataSourceSlug: 'meeting',
    searchPlaceholder: 'Search meetings'
  });

  if (!calendar.hasDateField) {
    return <div>This data source has no date field.</div>;
  }

  return (
    <div className="space-y-4">
      {calendar.toolbar}

      <CalendarProvider {...calendar.calendarProviderProps}>
        <Calendar />
      </CalendarProvider>
    </div>
  );
}

With explicit field slugs and color mapping

const calendar = useDocyrusCalendar({
  client,
  appSlug: 'base',
  dataSourceSlug: 'meeting',
  startDateFieldSlug: 'starts_at',
  endDateFieldSlug: 'ends_at',
  titleFieldSlug: 'subject',
  colorFieldSlug: 'meeting_type',
  descriptionFieldSlug: 'agenda',
  userFieldSlug: 'organizer',
  colorMap: {
    standup: 'blue',
    review: 'purple',
    leave: 'red',
    'all-hands': 'orange'
  },
  defaultView: 'week',
  defaultEventDurationMinutes: 30
});

Visible-range filtering

When events live in a large data source, fetching every record at once is wasteful. Set enableDateRangeFilter: true and the hook narrows the items query to the calendar's currently visible window using an overlap test:

const calendar = useDocyrusCalendar({
  client,
  appSlug: 'base',
  dataSourceSlug: 'meeting',
  enableDateRangeFilter: true
});

return (
  <CalendarProvider
    {...calendar.calendarProviderProps}
    onVisibleRangeChange={calendar.setVisibleRange}>
    <Calendar />
  </CalendarProvider>
);

The hook will refetch every time the user navigates the calendar (next month, switch to week view, etc.).

Custom event builder

Use getEvent when the default mapping is not enough — for example to derive the color from multiple fields or to skip records that should not appear on the calendar.

const calendar = useDocyrusCalendar<MeetingRow>({
  client,
  appSlug: 'base',
  dataSourceSlug: 'meeting',
  getEvent: (item, ctx) => {
    if (item.status === 'cancelled') return null;

    const start = new Date(item.starts_at);
    const end = new Date(item.ends_at);

    return {
      id: ctx.index + 1,
      recordId: String(item.id),
      startDate: start.toISOString(),
      endDate: end.toISOString(),
      title: `${item.subject} (${item.location ?? 'TBD'})`,
      description: item.agenda ?? '',
      color: item.priority === 'high' ? 'red' : 'blue',
      user: {
        id: item.organizer_id,
        name: item.organizer_name,
        picturePath: item.organizer_avatar ?? null
      },
      item
    };
  }
});

Using a custom collection adapter

If you maintain a typed collection layer (auto-generated from @docyrus/tanstack-db-generator or hand-written) and want to reuse it for the calendar, pass it via collection. The hook will use the collection's list / create / update / delete methods instead of calling the REST endpoints directly:

const collection = useMeetingCollection();

const calendar = useDocyrusCalendar({
  client,
  appSlug: 'base',
  dataSourceSlug: 'meeting',
  collection
});

Customizing the calendar UI

calendarProviderProps wires only the minimum required to render events and persist changes to Docyrus (events, users, defaultView, filterItems, onEventCreate, onEventUpdate, onEventDelete, onEventDrop).

Every other CalendarProvider prop is a passthrough — spread calendarProviderProps first, then add the props you need:

<CalendarProvider
  {...calendar.calendarProviderProps}
  onVisibleRangeChange={calendar.setVisibleRange}
  // Replace the built-in event dialog with your own form
  onEventClick={(event) => openMeetingDialog(event.recordId)}
  // Open a side sheet when an empty time slot is clicked
  onSlotClick={(start, end) => openCreateSheet(start, end)}
  // Hide UI you don't want
  hideUserSelect
  hideSettings
  // Only show two views in the tab bar
  visibleViews={['week', 'month']}
  // Custom labels
  addButtonLabel="New meeting"
  eventCountLabel="meetings"
  searchPlaceholder="Search meetings…">
  <Calendar />
</CalendarProvider>

Event interaction callbacks

Each callback below replaces the built-in dialog for that interaction. Leave it out and the calendar uses its bundled add / details / delete dialogs.

Header visibility toggles

Labels & placeholders

View configuration

Filter customization

The hook auto-derives filterItems from the user field. You can override the entire filter experience with these props:

Custom rendering

Settings the user controls

These live in the settings gear and persist to localStorage under the key calendar-settings. They are not part of CalendarProvider's prop API — show or hide the gear with hideSettings to control whether the user can change them.

How the query is built

Internally the hook reuses the saved-view state from useDocyrusDataGrid, then creates its own items query with a stronger columns list.

That means a user can save a view that hides the title or date field, but the hook will still request:

• id
• the resolved start date field
• the resolved end date field (when present)
• the resolved title field
• the resolved color field (when present)
• the resolved description field (when present)
• the resolved user field (when present)

So events keep rendering correctly while the rest of the data-view behavior still follows the active Docyrus view.

Field resolution

Start date field

Resolution order:

1. startDateFieldSlug
2. first field with type === 'field-date' or 'field-dateTime'

If no start date field can be resolved, the hook returns hasDateField: false and renders no events.

End date field

Resolution order:

1. endDateFieldSlug
2. first matching slug from: end_date, end_time, end_datetime, finish_date, due_date, deadline, ends_at, ended_at (excluding the start field)
3. first date / dateTime field different from the start field

When no end date field is available, the hook falls back to defaultEventDurationMinutes (60 minutes by default) to compute each event's end.

Title field

Resolution order:

1. titleFieldSlug
2. first matching slug from: name, title, label, subject, display_name, displayName, commercial_title, short_name

If no title can be resolved, events fall back to Event <index>.

Color field

Resolution order:

1. colorFieldSlug
2. field whose slug is color or colour

Description field

Resolution order:

1. descriptionFieldSlug
2. first matching slug from: description, notes, content, details, body, summary (excluding the title field)

User field

Resolution order:

1. userFieldSlug
2. first field with type === 'field-userSelect' or 'field-userMultiSelect'
3. field whose slug is record_owner

User values shape users[] (unique list used by the calendar's filter dropdown) and the filterItems[] array that powers the header filter.

Color resolution

Each record's color is normalized through this pipeline:

1. Read the raw value from colorField (string, enum option name, or object with a name / label / title / value string property).
2. Lower-case and trim the value.
3. Look up the value in colorMap (both original casing and lower-cased keys are tried).
4. If the value is already one of 'blue' | 'green' | 'red' | 'yellow' | 'purple' | 'orange', use it as-is.
5. Otherwise default to 'blue'.

This means a field-select whose option names are Standup, Review, Leave etc. can be mapped to event colors with a small map:

colorMap: {
  standup: 'blue',
  review: 'purple',
  leave: 'red'
}

Persistence (CRUD wiring)

calendarProviderProps plugs the calendar's lifecycle events into the Docyrus REST endpoints (or your custom collection adapter when provided):

If you need to create a new Docyrus record from the calendar (for example from an "Add event" toolbar button), call the exposed createRecord(startDate, endDate, extraValues?) helper. It posts to the items endpoint (or your collection.create) and reloads the calendar.

Loading lifecycle

The hook exposes three loading-related fields that map to different UX needs:

API Reference

useDocyrusCalendar(options)

The hook accepts every useDocyrusDataGrid option except data, enableItemsQuery, showSelectColumn, enableRowMarkers, and collection (replaced by the DocyrusCalendarCollection shape). It also accepts the options below.

Return value

Type Exports