[scheduler] Add an option to render the empty days in the agenda view (#20045)

Author: rita-codes

docs/data/scheduler/event-calendar/event-calendar.md

@@ -171,6 +171,7 @@ Available properties:
 - `toggleWeekendVisibility`: show/hide the menu item that toggles weekend visibility.
 - `toggleWeekNumberVisibility`: show/hide the menu item that toggles week number visibility.
 - `toggleAmpm`: show/hide the menu item that toggles 12/24‑hour time format.
+- `toggleEmptyDaysInAgenda`: show/hide the menu item that toggles the visibility of days with no events in the Agenda view.
 
 ```ts
 // will hide the menu

packages/x-scheduler-headless/package.json

@@ -24,6 +24,7 @@
     "./timeline": "./src/timeline/index.ts",
     "./timeline-provider": "./src/timeline-provider/index.ts",
     "./use-adapter": "./src/use-adapter/index.ts",
+    "./use-agenda-event-occurrences-grouped-by-day": "./src/use-agenda-event-occurrences-grouped-by-day/index.ts",
     "./use-day-list": "./src/use-day-list/index.ts",
     "./use-event-calendar": "./src/use-event-calendar/index.ts",
     "./use-event-calendar-store-context": "./src/use-event-calendar-store-context/index.ts",

packages/x-scheduler-headless/src/constants/constants.ts

@@ -13,3 +13,13 @@ export const SCHEDULER_RECURRING_EDITING_SCOPE: RecurringEventUpdateScope =
 export const EVENT_DRAG_PRECISION_MINUTE = 15;
 
 export const EVENT_DRAG_PRECISION_MS = EVENT_DRAG_PRECISION_MINUTE * 60 * 1000;
+
+/**
+ * Maximum number of days the Agenda view is allowed to scan forward
+ * when looking for event occurrences.
+ * This acts as a hard limit to prevent excessive iteration
+ */
+export const AGENDA_MAX_HORIZON_DAYS = 180;
+
+// TODO: Create a prop to allow users to customize the number of days in agenda view
+export const AGENDA_VIEW_DAYS_AMOUNT = 12;

packages/x-scheduler-headless/src/models/preferences.ts

@@ -22,6 +22,11 @@ export interface EventCalendarPreferences extends SchedulerPreferences {
    * @default true
    */
   isSidePanelOpen: boolean;
+  /**
+   * Whether empty days are shown in the agenda view.
+   * @default true
+   */
+  showEmptyDaysInAgenda: boolean;
 }
 
 export interface TimelinePreferences extends SchedulerPreferences {}
@@ -42,4 +47,9 @@ export interface EventCalendarPreferencesMenuConfig {
    * @default false
    */
   toggleAmpm: boolean;
+  /**
+   * Whether the menu item to toggle empty days in agenda view is visible.
+   * @default true
+   */
+  toggleEmptyDaysInAgenda: boolean;
 }

packages/x-scheduler-headless/src/standalone-event/StandaloneEvent.tsx

@@ -5,7 +5,7 @@ import { disableNativeDragPreview } from '@atlaskit/pragmatic-drag-and-drop/elem
 import { useEventCallback } from '@base-ui-components/utils/useEventCallback';
 import { useButton } from '../base-ui-copy/utils/useButton';
 import { useRenderElement } from '../base-ui-copy/utils/useRenderElement';
-import { BaseUIComponentProps } from '../base-ui-copy/utils/types';
+import { BaseUIComponentProps, NonNativeButtonProps } from '../base-ui-copy/utils/types';
 import { CalendarOccurrencePlaceholderExternalDragData } from '../models';
 import { useDragPreview } from '../utils/useDragPreview';
 
@@ -30,7 +30,10 @@ export const StandaloneEvent = React.forwardRef(function StandaloneEvent(
   const isInteractive = true;
 
   const ref = React.useRef<HTMLDivElement>(null);
-  const { getButtonProps, buttonRef } = useButton({ disabled: !isInteractive });
+  const { getButtonProps, buttonRef } = useButton({
+    disabled: !isInteractive,
+    native: false,
+  });
 
   const preview = useDragPreview({
     type: 'standalone-event',
@@ -95,6 +98,7 @@ export namespace StandaloneEvent {
 
   export interface Props
     extends BaseUIComponentProps<'div', State>,
+      NonNativeButtonProps,
       Pick<useDragPreview.Parameters, 'renderDragPreview' | 'data'> {
     /**
      * Callback fired when the event is dropped into the Event Calendar.

packages/x-scheduler-headless/src/use-agenda-event-occurrences-grouped-by-day/index.ts

@@ -0,0 +1 @@
+export * from './useAgendaEventOccurrencesGroupedByDay';

packages/x-scheduler-headless/src/use-agenda-event-occurrences-grouped-by-day/useAgendaEventOccurrencesGroupedByDay.test.tsx

@@ -0,0 +1,148 @@
+import * as React from 'react';
+import { renderHook } from '@mui/internal-test-utils';
+import { adapter } from 'test/utils/scheduler';
+import { processDate } from '../process-date';
+import { CalendarEvent, SchedulerValidDate } from '../models';
+import {
+  useAgendaEventOccurrencesGroupedByDay,
+  useAgendaEventOccurrencesGroupedByDayOptions,
+} from './useAgendaEventOccurrencesGroupedByDay';
+import { EventCalendarProvider } from '../event-calendar-provider/EventCalendarProvider';
+import { getIdsFromOccurrencesMap } from '../utils/SchedulerStore/tests/utils';
+import { AGENDA_VIEW_DAYS_AMOUNT } from '../constants';
+
+describe('useAgendaEventOccurrencesGroupedByDay', () => {
+  const createEvent = (
+    id: string,
+    startISO: string,
+    endISO: string,
+    extra: Partial<CalendarEvent> = {},
+  ): CalendarEvent => ({
+    id,
+    start: adapter.date(startISO),
+    end: adapter.date(endISO),
+    title: `Event ${id}`,
+    ...extra,
+  });
+
+  function testHook({
+    events = [],
+    visibleDate,
+    showWeekends,
+    showEmptyDaysInAgenda,
+  }: {
+    events?: CalendarEvent[];
+    visibleDate: SchedulerValidDate;
+    showWeekends: boolean;
+    showEmptyDaysInAgenda: boolean;
+  }): useAgendaEventOccurrencesGroupedByDayOptions.ReturnValue {
+    const wrapper = ({ children }: { children: React.ReactNode }) => (
+      <EventCalendarProvider
+        events={events}
+        resources={[]}
+        visibleDate={visibleDate}
+        preferences={{ showWeekends, showEmptyDaysInAgenda }}
+      >
+        {children}
+      </EventCalendarProvider>
+    );
+
+    const { result } = renderHook(() => useAgendaEventOccurrencesGroupedByDay(), { wrapper });
+    return result.current;
+  }
+
+  it('should return exactly AGENDA_VIEW_DAYS_AMOUNT days and fills occurrences with [] when there are no events and showEmptyDays=true', () => {
+    const res = testHook({
+      visibleDate: adapter.date('2024-01-01'),
+      showWeekends: true,
+      showEmptyDaysInAgenda: true,
+    });
+
+    expect(res.days).to.have.length(12);
+    for (const day of res.days) {
+      expect(res.occurrencesMap.get(day.key)).to.deep.equal([]);
+    }
+  });
+
+  it('should extend forward until it fills AGENDA_VIEW_DAYS_AMOUNT days that contain events when showEmptyDays=false', () => {
+    const events: CalendarEvent[] = [
+      createEvent('1', '2025-01-01', '2025-01-01'),
+      createEvent('2', '2025-01-03', '2025-01-03'),
+      createEvent('3', '2025-01-05', '2025-01-05'),
+      createEvent('4', '2025-01-08', '2025-01-08'),
+      createEvent('5', '2025-01-09', '2025-01-09'),
+      createEvent('6', '2025-01-10', '2025-01-10'),
+      createEvent('7', '2025-01-11', '2025-01-11'),
+      createEvent('8', '2025-01-13', '2025-01-13'),
+      createEvent('9', '2025-01-14', '2025-01-14'),
+      createEvent('10', '2025-01-16', '2025-01-16'),
+      createEvent('11', '2025-01-18', '2025-01-18'),
+      createEvent('12', '2025-01-20', '2025-01-20'),
+      createEvent('13', '2025-01-22', '2025-01-22'),
+      createEvent('14', '2025-01-24', '2025-01-24'),
+    ];
+
+    const res = testHook({
+      events,
+      visibleDate: adapter.date('2025-01-01'),
+      showWeekends: true,
+      showEmptyDaysInAgenda: false,
+    });
+
+    expect(res.days).to.have.length(AGENDA_VIEW_DAYS_AMOUNT);
+    const expectedKeys = [
+      processDate(adapter.date('2025-01-01'), adapter).key,
+      processDate(adapter.date('2025-01-03'), adapter).key,
+      processDate(adapter.date('2025-01-05'), adapter).key,
+      processDate(adapter.date('2025-01-08'), adapter).key,
+      processDate(adapter.date('2025-01-09'), adapter).key,
+      processDate(adapter.date('2025-01-10'), adapter).key,
+      processDate(adapter.date('2025-01-11'), adapter).key,
+      processDate(adapter.date('2025-01-13'), adapter).key,
+      processDate(adapter.date('2025-01-14'), adapter).key,
+      processDate(adapter.date('2025-01-16'), adapter).key,
+      processDate(adapter.date('2025-01-18'), adapter).key,
+      processDate(adapter.date('2025-01-20'), adapter).key,
+    ];
+    expect(res.days.map((day) => day.key)).to.deep.equal(expectedKeys);
+    for (const day of res.days) {
+      expect((res.occurrencesMap.get(day.key) ?? []).length).to.greaterThan(0);
+    }
+  });
+
+  it('should respect showWeekends preference when building the day list', () => {
+    const events: CalendarEvent[] = [
+      createEvent('1', '2025-10-03', '2025-10-03'), // Fri
+      createEvent('2', '2025-10-04', '2025-10-04'), // Sat
+      createEvent('3', '2025-10-05', '2025-10-05'), // Sun
+      createEvent('4', '2025-10-06', '2025-10-06'), // Mon
+      createEvent('5', '2025-10-07', '2025-10-07'), // Tue
+      createEvent('6', '2025-10-08', '2025-10-08'), // Wed
+      createEvent('7', '2025-10-09', '2025-10-09'), // Thu
+      createEvent('8', '2025-10-10', '2025-10-10'), // Fri
+      createEvent('9', '2025-10-11', '2025-10-11'), // Sat
+      createEvent('10', '2025-10-12', '2025-10-12'), // Sun
+      createEvent('11', '2025-10-13', '2025-10-13'), // Mon
+      createEvent('12', '2025-10-14', '2025-10-14'), // Tue
+      createEvent('13', '2025-10-15', '2025-10-15'), // Wed
+      createEvent('14', '2025-10-16', '2025-10-16'), // Thu
+      createEvent('15', '2025-10-17', '2025-10-17'), // Fri
+      createEvent('16', '2025-10-18', '2025-10-18'), // Sat
+      createEvent('17', '2025-10-19', '2025-10-19'), // Sun
+      createEvent('18', '2025-10-20', '2025-10-20'), // Mon
+    ];
+
+    const res = testHook({
+      events,
+      visibleDate: adapter.date('2025-10-03'), // Friday
+      showWeekends: false,
+      showEmptyDaysInAgenda: true,
+    });
+    expect(res.days).to.have.length(12);
+    const weekendIds = ['2', '3', '9', '10', '16', '17'];
+    const includedIds = getIdsFromOccurrencesMap(res.occurrencesMap);
+    for (const id of weekendIds) {
+      expect(includedIds).to.not.include(id);
+    }
+  });
+});

packages/x-scheduler-headless/src/use-agenda-event-occurrences-grouped-by-day/useAgendaEventOccurrencesGroupedByDay.ts

@@ -0,0 +1,138 @@
+'use client';
+
+import * as React from 'react';
+import { useStore } from '@base-ui-components/utils/store';
+import { useAdapter, diffIn } from '../use-adapter/useAdapter';
+import { useEventCalendarStoreContext } from '../use-event-calendar-store-context';
+import { selectors } from '../use-event-calendar';
+import { useDayList } from '../use-day-list';
+import { CalendarProcessedDate, CalendarEventOccurrence } from '../models';
+import { innerGetEventOccurrencesGroupedByDay } from '../use-event-occurrences-grouped-by-day';
+import { AGENDA_VIEW_DAYS_AMOUNT, AGENDA_MAX_HORIZON_DAYS } from '../constants';
+
+/**
+ * Agenda-specific hook that:
+ *  - Builds the day list starting at `date`
+ *  - Groups event occurrences by day
+ *  - If `showEmptyDays` is false, extends the range forward until it fills `amount` days that contain events (up to a horizon limit)
+ */
+export function useAgendaEventOccurrencesGroupedByDay(): useAgendaEventOccurrencesGroupedByDayOptions.ReturnValue {
+  const adapter = useAdapter();
+  const store = useEventCalendarStoreContext();
+
+  const getDayList = useDayList();
+
+  const events = useStore(store, selectors.events);
+  const visibleDate = useStore(store, selectors.visibleDate);
+  const showWeekends = useStore(store, selectors.showWeekends);
+  const showEmptyDays = useStore(store, selectors.showEmptyDaysInAgenda);
+  const visibleResources = useStore(store, selectors.visibleResourcesMap);
+
+  const amount = AGENDA_VIEW_DAYS_AMOUNT;
+
+  return React.useMemo(() => {
+    if (process.env.NODE_ENV !== 'production') {
+      if (amount <= 0) {
+        throw new Error(
+          `useAgendaEventOccurrencesGroupedByDay: The 'amount' parameter must be a positive number, but received ${amount}.`,
+        );
+      }
+    }
+
+    // 1) First chunk of days
+    let accumulatedDays = getDayList({
+      date: visibleDate,
+      amount,
+      excludeWeekends: !showWeekends,
+    });
+
+    // Compute occurrences for the current accumulated range
+    let occurrenceMap = innerGetEventOccurrencesGroupedByDay(
+      adapter,
+      accumulatedDays,
+      events,
+      visibleResources,
+    );
+
+    const hasEvents = (day: CalendarProcessedDate) => (occurrenceMap.get(day.key)?.length ?? 0) > 0;
+
+    // 2) If we show empty days, just return the amount days
+    if (showEmptyDays) {
+      const finalOccurrences = new Map(
+        accumulatedDays.map((d) => [d.key, occurrenceMap.get(d.key) ?? []]),
+      );
+      return { days: accumulatedDays, occurrencesMap: finalOccurrences };
+    }
+
+    // 3) If we hide empty days, keep extending forward in blocks until we fill `amount` days with events
+    let daysWithEvents = accumulatedDays.filter(hasEvents).slice(0, amount);
+
+    while (daysWithEvents.length < amount) {
+      // Stop if the calendar span already reaches the horizon
+      const first = accumulatedDays[0]?.value;
+      const last = accumulatedDays[accumulatedDays.length - 1]?.value;
+
+      if (first && last) {
+        const spanDays =
+          diffIn(adapter, adapter.startOfDay(last), adapter.startOfDay(first), 'days') + 1;
+
+        // Hard stop to avoid scanning too far into the future
+        if (spanDays >= AGENDA_MAX_HORIZON_DAYS) {
+          break;
+        }
+      }
+
+      // Extend forward by one more chunk and recompute occurrences over the accumulated range
+      const nextStart = adapter.addDays(
+        accumulatedDays[accumulatedDays.length - 1]?.value ?? visibleDate,
+        1,
+      );
+
+      const more = getDayList({
+        date: nextStart,
+        amount,
+        excludeWeekends: !showWeekends,
+      });
+
+      accumulatedDays = accumulatedDays.concat(more);
+
+      occurrenceMap = innerGetEventOccurrencesGroupedByDay(
+        adapter,
+        accumulatedDays,
+        events,
+        visibleResources,
+      );
+
+      daysWithEvents = accumulatedDays.filter(hasEvents).slice(0, amount);
+    }
+
+    // Keep occurrences only for the final visible days
+    const filledKeys = new Set(daysWithEvents.map((d) => d.key));
+    const finalOccurrences = new Map([...occurrenceMap].filter(([key]) => filledKeys.has(key)));
+
+    return { days: daysWithEvents, occurrencesMap: finalOccurrences };
+  }, [
+    getDayList,
+    visibleDate,
+    amount,
+    showWeekends,
+    adapter,
+    events,
+    visibleResources,
+    showEmptyDays,
+  ]);
+}
+
+export namespace useAgendaEventOccurrencesGroupedByDayOptions {
+  export type ReturnValue = {
+    /**
+     * Final visible days in the agenda.
+     */
+    days: CalendarProcessedDate[];
+    /**
+     * The occurrences Map as returned by `useEventOccurrences()`.
+     * It should contain the occurrences for each requested day but can also contain occurrences for other days.
+     */
+    occurrencesMap: Map<string, CalendarEventOccurrence[]>;
+  };
+}

packages/x-scheduler-headless/src/use-event-calendar/EventCalendarStore.selectors.ts

@@ -12,6 +12,7 @@ export const selectors = {
   ampm: createSelector((state: State) => state.preferences.ampm),
   showWeekends: createSelector((state: State) => state.preferences.showWeekends),
   showWeekNumber: createSelector((state: State) => state.preferences.showWeekNumber),
+  showEmptyDaysInAgenda: createSelector((state: State) => state.preferences.showEmptyDaysInAgenda),
   hasDayView: createSelector((state: State) => state.views.includes('day')),
   isEventDraggable: createSelector(
     schedulerSelectors.isEventReadOnly,

packages/x-scheduler-headless/src/use-event-calendar/EventCalendarStore.ts

@@ -15,12 +15,14 @@ export const DEFAULT_VIEW: CalendarView = 'week';
 export const DEFAULT_PREFERENCES: EventCalendarPreferences = {
   showWeekends: true,
   showWeekNumber: false,
+  showEmptyDaysInAgenda: true,
   isSidePanelOpen: true,
   ampm: true,
 };
 export const DEFAULT_PREFERENCES_MENU_CONFIG: EventCalendarPreferencesMenuConfig = {
   toggleWeekendVisibility: true,
   toggleWeekNumberVisibility: true,
+  toggleEmptyDaysInAgenda: true,
   toggleAmpm: true,
 };