Calendar Views — cdx_calendar_view

cdx_calendar_view is the CDX query-driven calendar shell. Use it when a collection is naturally organized by date while the right side remains an ordinary detail surface.

import 'package:cdx_calendar_view/cdx_calendar_view.dart';

Live Example

Open the full route: Calendar View.

When To Use It

Use a calendar view when the primary question is what is scheduled or active on this date range?

Good fits:

Scenario	Pattern
Scheduled activities	Calendar rail selects a day/week/month; detail pane shows rows
Maintenance plans	Date buckets show upcoming work and overdue work
Training events	Month or week mode selects sessions for a table/detail pane
Release windows	Date range drives a filtered entity list

Model

CalendarQuery
  -> CalendarDataSource<T>
  -> CalendarController<T>
  -> CalendarShell<T>

CalendarQuery composes root filters, search, sorting, and selected date ranges through cdx_query. CalendarDataSource<T> owns transport. CalendarController<T> owns buckets, selected range, and selected rows. CalendarShell<T> renders the resizable calendar rail and delegates the right side to your builder.

Calendar Shell

class ActivityCalendarDataSource extends CalendarDataSource<Activity> {
  ActivityCalendarDataSource(ActivityApi api)
    : _api = api,
      super(
        CalendarQuery(
          dateField: 'scheduled_at',
          baseFilter: siteFilter,
        ),
      );

  final ActivityApi _api;

  @override
  Future<List<CalendarDateBucket>> fetchBuckets(CalendarDateRange range) {
    return _api.fetchDateBuckets(
      groupBy: query.bucketGroupBy(),
      filter: query.filterForRange(range),
    );
  }

  @override
  Future<CalendarItemsPage<Activity>> fetchItems(
    CalendarDateRange range, {
    int limit = 20,
    int offset = 0,
  }) {
    return _api.fetchActivities(
      filter: query.filterForRange(range),
      search: query.search,
      orderBy: query.orderBy,
      limit: limit,
      offset: offset,
    );
  }
}

final controller = CalendarController<Activity>(
  dataSource: ActivityCalendarDataSource(api),
);

CalendarShell<Activity>(
  controller: controller,
  detailBuilder: (context, controller) {
    return ActivityTable(
      range: controller.selectedRange,
      items: controller.items,
      total: controller.total,
      page: controller.page,
      onPageChanged: controller.goToPage,
    );
  },
);

The renderer is CDX-owned. Year, month, and week modes share the same grid treatment so spacing, disabled state, selection, and count rendering stay consistent across modes.

Query Boundary

The calendar contributes a date-range filter. The detail surface can still own its own search, sort, and extra filters:

calendar date range filter
AND base filter
AND detail search/filter/sort

That keeps the calendar as context while preserving the ergonomics of a normal table, kanban, or detail pane.

API Parameters

Type	Parameter	Purpose
CalendarQuery	dateField	Query field used for buckets and selected-range filters.
CalendarQuery	baseFilter	Predicate applied to every bucket and selected-detail fetch.
CalendarQuery	search	Optional free-text search for concrete data sources.
CalendarQuery	orderBy	Ordering for selected-detail rows.
CalendarQuery	timezone	Optional bucketing timezone.
CalendarDataSource	query	Owned by the source, not the controller.
CalendarController	pageSize	Row page size for selected-range detail fetches.
CalendarController	maxCachedBucketRanges	Number of visible bucket ranges kept in memory.
CalendarShell	dateFields, selectedDateField	Optional field switcher in the calendar rail.
CalendarShell	onDateFieldChanged, onModeChanged, onFocusedDayChanged, onSelectedRangeChanged	Host callbacks for shell state changes.

Cross-links

• Data Tables — common detail surface beside the calendar rail
• Search and Filters — shared cdx_query vocabulary
• Layout & Navigation — master/detail and responsive shell primitives