Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

Add XDSSchedule lab component (#2366)

Andrey Goder60b62ee0cb48
diff --git a/apps/storybook/stories/Schedule.stories.tsx b/apps/storybook/stories/Schedule.stories.tsx
new file mode 100644
index 0000000000..84e95dd2fc
--- /dev/null
+++ b/apps/storybook/stories/Schedule.stories.tsx
@@ -0,0 +1,393 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {useMemo, useState} from 'react';
+import type {Meta, StoryObj} from '@storybook/react';
+import {
+ XDSSchedule,
+ createXDSScheduleDayView,
+ createXDSScheduleListView,
+ createXDSScheduleMonthlyView,
+ createXDSScheduleWeeklyView,
+ createEventFromISO,
+ type CalendarEvent,
+ type Instant,
+ type XDSScheduleCategory,
+ type XDSScheduleViewSelectorOption,
+ useXDSSchedulePaginationPlugin,
+ useXDSScheduleViewSelectorPlugin,
+} from '@xds/lab';
+
+const storyNow = new Date();
+const focusDate = storyNow.getTime() as Instant;
+const currentWeekStart = startOfWeek(storyNow);
+
+const categories: XDSScheduleCategory[] = [
+ {label: 'Company', color: 'blue'},
+ {label: 'Design', color: 'purple'},
+ {label: 'Launch', color: 'green'},
+ {label: 'Focus', color: 'teal'},
+ {label: 'Holiday', color: 'yellow'},
+ {label: 'Retro', color: 'orange'},
+ {label: 'Incident', color: 'red'},
+ {label: 'Migration', color: 'pink'},
+];
+
+const events: CalendarEvent[] = [
+ createEventFromISO({
+ id: 'all-hands',
+ title: 'Company all hands',
+ category: 'Company',
+ start: dateTimeISO(storyNow, 9),
+ end: dateTimeISO(storyNow, 10),
+ }),
+ createEventFromISO({
+ id: 'all-hands-previous-day',
+ title: 'Company all hands',
+ category: 'Company',
+ start: dateTimeISO(addDays(storyNow, -1), 9),
+ end: dateTimeISO(addDays(storyNow, -1), 10),
+ }),
+ createEventFromISO({
+ id: 'all-hands-next-day',
+ title: 'Company all hands',
+ category: 'Company',
+ start: dateTimeISO(addDays(storyNow, 1), 9),
+ end: dateTimeISO(addDays(storyNow, 1), 10),
+ }),
+ createEventFromISO({
+ id: 'design-review',
+ title: 'Design review',
+ category: 'Design',
+ start: dateTimeISO(storyNow, 11),
+ end: dateTimeISO(storyNow, 12, 30),
+ }),
+ createEventFromISO({
+ id: 'launch',
+ title: 'Launch window',
+ category: 'Launch',
+ start: dateISO(addDays(currentWeekStart, 3)),
+ end: dateISO(addDays(currentWeekStart, 4)),
+ }),
+ createEventFromISO({
+ id: 'focus-day',
+ title: 'Focus day',
+ category: 'Focus',
+ start: dateISO(storyNow),
+ end: dateISO(storyNow),
+ }),
+ createEventFromISO({
+ id: 'company-holiday',
+ title: 'Company holiday',
+ category: 'Holiday',
+ start: dateISO(addDays(currentWeekStart, 6)),
+ end: dateISO(addDays(currentWeekStart, 6)),
+ }),
+ createEventFromISO({
+ id: 'retro',
+ title: 'Weekly retro',
+ category: 'Retro',
+ start: dateTimeISO(addDays(currentWeekStart, 5), 14),
+ end: dateTimeISO(addDays(currentWeekStart, 5), 15),
+ }),
+ createEventFromISO({
+ id: 'incident',
+ title: 'Incident review',
+ category: 'Incident',
+ start: dateTimeISO(addDays(currentWeekStart, 1), 10, 30),
+ end: dateTimeISO(addDays(currentWeekStart, 1), 11, 30),
+ }),
+ createEventFromISO({
+ id: 'overnight-migration',
+ title: 'Overnight migration',
+ category: 'Migration',
+ start: dateTimeISO(addDays(currentWeekStart, 5), 23, 30),
+ end: dateTimeISO(addDays(currentWeekStart, 6), 2),
+ }),
+];
+
+const meta: Meta<typeof XDSSchedule> = {
+ title: 'Lab/Schedule',
+ component: XDSSchedule,
+ tags: ['autodocs'],
+ parameters: {
+ layout: 'fullscreen',
+ },
+ decorators: [
+ Story => (
+ <div style={{padding: 24, minHeight: '100vh'}}>
+ <Story />
+ </div>
+ ),
+ ],
+};
+
+export default meta;
+
+type Story = StoryObj<typeof XDSSchedule>;
+
+function addDays(date: Date, days: number): Date {
+ const nextDate = new Date(date);
+ nextDate.setDate(nextDate.getDate() + days);
+ return nextDate;
+}
+
+function startOfWeek(date: Date): Date {
+ const startDate = new Date(date);
+ startDate.setHours(12, 0, 0, 0);
+ startDate.setDate(startDate.getDate() - startDate.getDay());
+ return startDate;
+}
+
+function dateISO(date: Date): string {
+ const year = date.getFullYear();
+ const month = String(date.getMonth() + 1).padStart(2, '0');
+ const day = String(date.getDate()).padStart(2, '0');
+ return `${year}-${month}-${day}`;
+}
+
+function dateTimeISO(date: Date, hour: number, minute: number = 0): string {
+ const dateTime = new Date(date);
+ dateTime.setHours(hour, minute, 0, 0);
+ return dateTime.toISOString();
+}
+
+function makeSeededRandom(seed: number): () => number {
+ let value = seed;
+ return () => {
+ value = (value * 1664525 + 1013904223) % 4294967296;
+ return value / 4294967296;
+ };
+}
+
+function createAsyncEvents(start: Instant, end: Instant): CalendarEvent[] {
+ const random = makeSeededRandom(Math.floor(start / 86400000));
+ const asyncCategories = categories.slice(0, 6);
+ const titles = [
+ 'Planning sync',
+ 'Design critique',
+ 'Customer review',
+ 'Metrics readout',
+ 'Launch check',
+ 'Office hours',
+ ];
+ const generatedEvents: CalendarEvent[] = [];
+
+ for (let dayStart = start; dayStart < end; dayStart += 24 * 60 * 60 * 1000) {
+ const eventCount = 1 + Math.floor(random() * 3);
+ const day = new Date(dayStart);
+
+ for (let index = 0; index < eventCount; index++) {
+ const startHour = 8 + Math.floor(random() * 8);
+ const startMinute = random() > 0.65 ? 30 : 0;
+ const durationHours = 1 + Math.floor(random() * 2);
+ const title = titles[Math.floor(random() * titles.length)];
+ const category =
+ asyncCategories[Math.floor(random() * asyncCategories.length)];
+ generatedEvents.push(
+ createEventFromISO({
+ id: `${dayStart}:${index}`,
+ title,
+ category: category.label,
+ start: dateTimeISO(day, startHour, startMinute),
+ end: dateTimeISO(day, startHour + durationHours, startMinute),
+ }),
+ );
+ }
+
+ if (random() > 0.68) {
+ generatedEvents.push(
+ createEventFromISO({
+ id: `${dayStart}:all-day`,
+ title: 'Focus day',
+ category:
+ asyncCategories[Math.floor(random() * asyncCategories.length)]
+ .label,
+ start: dateISO(day),
+ end: dateISO(day),
+ }),
+ );
+ }
+ }
+
+ return generatedEvents;
+}
+
+export const Monthly: Story = {
+ render: () => {
+ const [date, setDate] = useState<Instant>(focusDate);
+ const view = useMemo(() => createXDSScheduleMonthlyView(), []);
+
+ return (
+ <XDSSchedule
+ view={view}
+ events={events}
+ categories={categories}
+ date={date}
+ focusDate={focusDate}
+ onChangeDate={setDate}
+ timezoneID="America/Los_Angeles"
+ />
+ );
+ },
+};
+
+export const Weekly: Story = {
+ render: () => {
+ const [date, setDate] = useState<Instant>(focusDate);
+ const view = useMemo(
+ () => createXDSScheduleWeeklyView({minHour: 7, maxHour: 19}),
+ [],
+ );
+
+ return (
+ <XDSSchedule
+ view={view}
+ events={events}
+ categories={categories}
+ date={date}
+ onChangeDate={setDate}
+ timezoneID="America/Los_Angeles"
+ />
+ );
+ },
+};
+
+export const WeeklyFixedHeight: Story = {
+ render: () => {
+ const [date, setDate] = useState<Instant>(focusDate);
+ const view = useMemo(
+ () => createXDSScheduleWeeklyView({minHour: 7, maxHour: 19}),
+ [],
+ );
+
+ return (
+ <div style={{height: 520}}>
+ <XDSSchedule
+ view={view}
+ events={events}
+ categories={categories}
+ date={date}
+ onChangeDate={setDate}
+ timezoneID="America/Los_Angeles"
+ style={{height: '100%'}}
+ />
+ </div>
+ );
+ },
+};
+
+export const Day: Story = {
+ render: () => {
+ const [date, setDate] = useState<Instant>(focusDate);
+ const view = useMemo(() => createXDSScheduleDayView(), []);
+
+ return (
+ <XDSSchedule
+ view={view}
+ events={events}
+ categories={categories}
+ date={date}
+ focusDate={focusDate}
+ onChangeDate={setDate}
+ timezoneID="America/Los_Angeles"
+ />
+ );
+ },
+};
+
+export const List: Story = {
+ render: () => {
+ const [date, setDate] = useState<Instant>(focusDate);
+ const view = useMemo(() => createXDSScheduleListView(), []);
+
+ return (
+ <XDSSchedule
+ view={view}
+ events={events}
+ categories={categories}
+ date={date}
+ focusDate={focusDate}
+ onChangeDate={setDate}
+ timezoneID="America/Los_Angeles"
+ />
+ );
+ },
+};
+
+export const AsyncLoader: Story = {
+ render: () => {
+ const [date, setDate] = useState<Instant>(focusDate);
+ const view = useMemo(
+ () => createXDSScheduleWeeklyView({minHour: 7, maxHour: 19}),
+ [],
+ );
+ const loadEvents = async (
+ start: Instant,
+ end: Instant,
+ ): Promise<CalendarEvent[]> => {
+ await new Promise(resolve => setTimeout(resolve, 300));
+ return createAsyncEvents(start, end);
+ };
+
+ return (
+ <XDSSchedule
+ view={view}
+ events={loadEvents}
+ categories={categories}
+ date={date}
+ focusDate={focusDate}
+ onChangeDate={setDate}
+ timezoneID="America/Los_Angeles"
+ />
+ );
+ },
+};
+
+export const ViewSelectorPlugin: Story = {
+ render: () => {
+ const views = useMemo(
+ () => ({
+ month: createXDSScheduleMonthlyView(),
+ week: createXDSScheduleWeeklyView({minHour: 7, maxHour: 19}),
+ day: createXDSScheduleDayView({minHour: 8, maxHour: 18}),
+ list: createXDSScheduleListView(),
+ }),
+ [],
+ );
+ type StoryScheduleView = (typeof views)[keyof typeof views];
+ const [view, setView] = useState<StoryScheduleView>(() => views.week);
+ const [date, setDate] = useState<Instant>(focusDate);
+ const viewOptions = useMemo<
+ ReadonlyArray<XDSScheduleViewSelectorOption<StoryScheduleView>>
+ >(
+ () => [
+ {view: views.month, label: 'Month'},
+ {view: views.week, label: 'Week'},
+ {view: views.day, label: 'Day'},
+ {view: views.list, label: 'List'},
+ ],
+ [views],
+ );
+ const paginationPlugin = useXDSSchedulePaginationPlugin();
+ const viewSelectorPlugin = useXDSScheduleViewSelectorPlugin(viewOptions, {
+ onChangeView: setView,
+ });
+ const plugins = useMemo(
+ () => [paginationPlugin, viewSelectorPlugin],
+ [paginationPlugin, viewSelectorPlugin],
+ );
+
+ return (
+ <XDSSchedule
+ view={view}
+ events={events}
+ categories={categories}
+ date={date}
+ focusDate={focusDate}
+ onChangeDate={setDate}
+ timezoneID="America/Los_Angeles"
+ plugins={plugins}
+ />
+ );
+ },
+};
diff --git a/packages/core/src/utils/index.ts b/packages/core/src/utils/index.ts
index d59b615e79..b8287d3648 100644
--- a/packages/core/src/utils/index.ts
+++ b/packages/core/src/utils/index.ts
@@ -29,11 +29,17 @@ export {
plainDateDayOfWeek,
plainDateAddMonths,
plainDateAddDays,
+ plainDateToInstant,
+ plainDateFromInstant,
plainDateIsBefore,
plainDateIsAfter,
plainDateIsEqual,
+ plainDateMax,
+ plainDateMin,
plainDateIsInRange,
plainDateSetFirstOfMonth,
+ plainDateSetStartOfWeek,
+ plainDateSetEndOfWeekExclusive,
plainDateGetWeekNumber,
plainDateFormat,
DATE_FORMAT_WITH_WEEKDAY,
diff --git a/packages/core/src/utils/plainDate.test.ts b/packages/core/src/utils/plainDate.test.ts
index 12abfd9838..31f442a94d 100644
--- a/packages/core/src/utils/plainDate.test.ts
+++ b/packages/core/src/utils/plainDate.test.ts
@@ -13,11 +13,17 @@ import {
plainDateDayOfWeek,
plainDateAddMonths,
plainDateAddDays,
+ plainDateToInstant,
+ plainDateFromInstant,
plainDateIsBefore,
plainDateIsAfter,
plainDateIsEqual,
+ plainDateMax,
+ plainDateMin,
plainDateIsInRange,
plainDateSetFirstOfMonth,
+ plainDateSetStartOfWeek,
+ plainDateSetEndOfWeekExclusive,
plainDateGetWeekNumber,
plainDateFormat,
DATE_FORMAT_WITH_WEEKDAY,
@@ -287,6 +293,38 @@ describe('plainDateAddDays', () => {
});
});
+describe('plainDateToInstant / plainDateFromInstant', () => {
+ it('converts a PlainDate to midnight in the requested timezone', () => {
+ expect(
+ plainDateToInstant(
+ {year: 2026, month: 5, day: 13},
+ 'America/Los_Angeles',
+ ),
+ ).toBe(Date.UTC(2026, 4, 13, 7));
+ });
+
+ it('roundtrips a PlainDate in the requested timezone', () => {
+ const date: PlainDate = {year: 2026, month: 5, day: 13};
+ expect(
+ plainDateFromInstant(
+ plainDateToInstant(date, 'America/Los_Angeles'),
+ 'America/Los_Angeles',
+ ),
+ ).toEqual(date);
+ });
+
+ it('supports explicit time components', () => {
+ expect(
+ plainDateToInstant(
+ {year: 2026, month: 5, day: 13},
+ 'America/Los_Angeles',
+ 9,
+ 30,
+ ),
+ ).toBe(Date.UTC(2026, 4, 13, 16, 30));
+ });
+});
+
describe('plainDateIsBefore / plainDateIsAfter', () => {
it('returns false for equal dates (isBefore)', () => {
expect(
@@ -372,6 +410,27 @@ describe('plainDateIsEqual', () => {
});
});
+describe('plainDateMax / plainDateMin', () => {
+ const earlier: PlainDate = {year: 2026, month: 1, day: 14};
+ const later: PlainDate = {year: 2026, month: 1, day: 15};
+
+ it('returns the later date for max', () => {
+ expect(plainDateMax(earlier, later)).toBe(later);
+ expect(plainDateMax(later, earlier)).toBe(later);
+ });
+
+ it('returns the earlier date for min', () => {
+ expect(plainDateMin(earlier, later)).toBe(earlier);
+ expect(plainDateMin(later, earlier)).toBe(earlier);
+ });
+
+ it('returns the first date when dates are equal', () => {
+ const equal: PlainDate = {year: 2026, month: 1, day: 15};
+ expect(plainDateMax(later, equal)).toBe(later);
+ expect(plainDateMin(later, equal)).toBe(later);
+ });
+});
+
describe('plainDateIsInRange', () => {
const start: PlainDate = {year: 2026, month: 1, day: 10};
const end: PlainDate = {year: 2026, month: 1, day: 20};
@@ -403,6 +462,26 @@ describe('plainDateIsInRange', () => {
});
});
+describe('plainDateSetStartOfWeek / plainDateSetEndOfWeekExclusive', () => {
+ it('returns the start of the week for a Sunday-start week', () => {
+ expect(plainDateSetStartOfWeek({year: 2026, month: 5, day: 13}, 0)).toEqual(
+ {year: 2026, month: 5, day: 10},
+ );
+ });
+
+ it('returns the start of the week for a Monday-start week', () => {
+ expect(plainDateSetStartOfWeek({year: 2026, month: 5, day: 13}, 1)).toEqual(
+ {year: 2026, month: 5, day: 11},
+ );
+ });
+
+ it('returns the exclusive end of the week', () => {
+ expect(
+ plainDateSetEndOfWeekExclusive({year: 2026, month: 5, day: 13}, 0),
+ ).toEqual({year: 2026, month: 5, day: 17});
+ });
+});
+
describe('plainDateSetFirstOfMonth', () => {
it('returns first day of the same month', () => {
expect(plainDateSetFirstOfMonth({year: 2026, month: 3, day: 15})).toEqual({
diff --git a/packages/core/src/utils/plainDate.ts b/packages/core/src/utils/plainDate.ts
index 0b827682cd..be573e3641 100644
--- a/packages/core/src/utils/plainDate.ts
+++ b/packages/core/src/utils/plainDate.ts
@@ -83,6 +83,79 @@ export function plainDateAddDays(pd: PlainDate, n: number): PlainDate {
return plainDateFromDate(d);
}
+function getTimeZoneParts(
+ instant: number,
+ timezoneID: string,
+): {
+ year: number;
+ month: number;
+ day: number;
+ hour: number;
+ minute: number;
+ second: number;
+} {
+ const parts = new Intl.DateTimeFormat('en-US', {
+ timeZone: timezoneID,
+ year: 'numeric',
+ month: '2-digit',
+ day: '2-digit',
+ hour: '2-digit',
+ minute: '2-digit',
+ second: '2-digit',
+ hourCycle: 'h23',
+ }).formatToParts(new Date(instant));
+
+ const lookup = Object.fromEntries(
+ parts
+ .filter(part => part.type !== 'literal')
+ .map(part => [part.type, Number(part.value)]),
+ );
+
+ return {
+ year: lookup.year,
+ month: lookup.month,
+ day: lookup.day,
+ hour: lookup.hour,
+ minute: lookup.minute,
+ second: lookup.second,
+ };
+}
+
+function getTimezoneOffsetMS(timezoneID: string, instant: number): number {
+ const parts = getTimeZoneParts(instant, timezoneID);
+ return (
+ Date.UTC(
+ parts.year,
+ parts.month - 1,
+ parts.day,
+ parts.hour,
+ parts.minute,
+ parts.second,
+ ) - instant
+ );
+}
+
+export function plainDateToInstant(
+ date: PlainDate,
+ timezoneID: string,
+ hour = 0,
+ minute = 0,
+): number {
+ const utcGuess = Date.UTC(date.year, date.month - 1, date.day, hour, minute);
+ const firstOffset = getTimezoneOffsetMS(timezoneID, utcGuess);
+ const firstInstant = utcGuess - firstOffset;
+ const secondOffset = getTimezoneOffsetMS(timezoneID, firstInstant);
+ return utcGuess - secondOffset;
+}
+
+export function plainDateFromInstant(
+ instant: number,
+ timezoneID: string,
+): PlainDate {
+ const parts = getTimeZoneParts(instant, timezoneID);
+ return plainDateCreate(parts.year, parts.month, parts.day);
+}
+
function compare(a: PlainDate, b: PlainDate): number {
if (a.year !== b.year) {
return a.year - b.year;
@@ -105,6 +178,14 @@ export function plainDateIsEqual(a: PlainDate, b: PlainDate): boolean {
return compare(a, b) === 0;
}
+export function plainDateMax(a: PlainDate, b: PlainDate): PlainDate {
+ return compare(a, b) >= 0 ? a : b;
+}
+
+export function plainDateMin(a: PlainDate, b: PlainDate): PlainDate {
+ return compare(a, b) <= 0 ? a : b;
+}
+
export function plainDateIsInRange(
pd: PlainDate,
range: [PlainDate, PlainDate],
@@ -116,6 +197,22 @@ export function plainDateSetFirstOfMonth(pd: PlainDate): PlainDate {
return {year: pd.year, month: pd.month, day: 1};
}
+export function plainDateSetStartOfWeek(
+ pd: PlainDate,
+ weekStartsOn: number,
+): PlainDate {
+ const day = plainDateDayOfWeek(pd);
+ const delta = (day - weekStartsOn + 7) % 7;
+ return plainDateAddDays(pd, -delta);
+}
+
+export function plainDateSetEndOfWeekExclusive(
+ pd: PlainDate,
+ weekStartsOn: number,
+): PlainDate {
+ return plainDateAddDays(plainDateSetStartOfWeek(pd, weekStartsOn), 7);
+}
+
export function plainDateGetWeekNumber(pd: PlainDate): number {
const d = plainDateToDate(pd);
const dayNum = d.getDay() || 7;
diff --git a/packages/lab/src/Schedule/CalendarEvent.ts b/packages/lab/src/Schedule/CalendarEvent.ts
new file mode 100644
index 0000000000..6d4deaee48
--- /dev/null
+++ b/packages/lab/src/Schedule/CalendarEvent.ts
@@ -0,0 +1,74 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file CalendarEvent.ts
+ * @input ISO event definitions and PlainDate/Instant primitives
+ * @output Calendar event types and event construction helpers
+ * @position Public schedule event model; consumed by XDSSchedule and views
+ */
+
+import {
+ plainDateFromISO,
+ type ISODateString,
+ type PlainDate,
+} from '@xds/core/utils';
+import type {XDSTokenColor} from '@xds/core/Token';
+import type {Instant} from './types';
+
+const DATE_ONLY_RE = /^\d{4}-\d{2}-\d{2}$/;
+
+export type XDSScheduleEventColor = Exclude<XDSTokenColor, 'default'>;
+
+export interface XDSScheduleCategory {
+ label: string;
+ color: XDSScheduleEventColor;
+}
+
+export interface CalendarEventBase {
+ id: string;
+ title: string;
+ category?: string;
+}
+
+export interface CalendarDayEvent extends CalendarEventBase {
+ start: PlainDate;
+ end: PlainDate;
+}
+
+export interface CalendarInstantEvent extends CalendarEventBase {
+ start: Instant;
+ end: Instant;
+}
+
+export type CalendarEvent = CalendarDayEvent | CalendarInstantEvent;
+
+export function createEventFromISO({
+ id,
+ title,
+ category,
+ start,
+ end,
+}: {
+ id: string;
+ title: string;
+ category?: CalendarEvent['category'];
+ start: string;
+ end: string;
+}): CalendarEvent {
+ if (DATE_ONLY_RE.test(start) && DATE_ONLY_RE.test(end)) {
+ return {
+ id,
+ title,
+ category,
+ start: plainDateFromISO(start as ISODateString),
+ end: plainDateFromISO(end as ISODateString),
+ };
+ }
+ return {
+ id,
+ title,
+ category,
+ start: Date.parse(start) as Instant,
+ end: Date.parse(end) as Instant,
+ };
+}
diff --git a/packages/lab/src/Schedule/DayView.tsx b/packages/lab/src/Schedule/DayView.tsx
new file mode 100644
index 0000000000..2eb0103fc4
--- /dev/null
+++ b/packages/lab/src/Schedule/DayView.tsx
@@ -0,0 +1,112 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file DayView.tsx
+ * @input XDSSchedule context and day view options
+ * @output Single-day time-grid schedule view factory
+ * @position Concrete schedule view; exported as createXDSScheduleDayView
+ */
+
+import {
+ DATE_FORMAT_WITH_WEEKDAY,
+ plainDateAddDays,
+ plainDateFormat,
+} from '@xds/core/utils';
+import {enumerateDates, getScheduleRangeFromDates} from './dateMath';
+import {useXDSScheduleContext} from './context';
+import {ScheduleMonthTitle, ScheduleFrame} from './shared';
+import {TimeGridView} from './TimeGridView';
+import {scheduleRangeToZonedDateTimeRange} from './zonedDateTime';
+import type {
+ PlainDate,
+ XDSScheduleView,
+ XDSScheduleViewComponentProps,
+} from './types';
+
+export interface XDSScheduleDayViewOptions {
+ minHour?: number;
+ maxHour?: number;
+ hourHeight?: number;
+}
+
+function XDSScheduleDayView({
+ options,
+}: XDSScheduleViewComponentProps<XDSScheduleDayViewOptions>) {
+ const {events, date, focusDate, timezoneID, range, isLoading} =
+ useXDSScheduleContext();
+ const {minHour = 0, maxHour = 24, hourHeight = 100} = options;
+ const rangeDate = date.toPlainDate();
+ const days = enumerateDates(range.startDate, range.endDate);
+ const titleLabel = plainDateFormat(rangeDate, DATE_FORMAT_WITH_WEEKDAY);
+
+ return (
+ <ScheduleFrame
+ title={<ScheduleMonthTitle date={rangeDate} timezoneID={timezoneID} />}
+ titleLabel={titleLabel}
+ isLoading={isLoading}>
+ <TimeGridView
+ days={days}
+ events={events}
+ focusDate={focusDate.toPlainDate()}
+ timezoneID={timezoneID}
+ minHour={minHour}
+ maxHour={maxHour}
+ hourHeight={hourHeight}
+ />
+ </ScheduleFrame>
+ );
+}
+
+export function createXDSScheduleDayView({
+ minHour = 0,
+ maxHour = 24,
+ hourHeight = 100,
+}: XDSScheduleDayViewOptions = {}): XDSScheduleView<XDSScheduleDayViewOptions> {
+ return {
+ component: XDSScheduleDayView,
+ options: {minHour, maxHour, hourHeight},
+ getDateRange: date => {
+ const range = getDayDateRange({
+ date: date.toPlainDate(),
+ timezoneID: date.timezoneID,
+ });
+ return scheduleRangeToZonedDateTimeRange(range, date.timezoneID);
+ },
+ getPreviousDateRange: date => {
+ const range = getDayDateRange({
+ date: plainDateAddDays(date.toPlainDate(), -1),
+ timezoneID: date.timezoneID,
+ });
+ return {
+ label: 'Previous day',
+ range: scheduleRangeToZonedDateTimeRange(range, date.timezoneID),
+ };
+ },
+ getNextDateRange: date => {
+ const range = getDayDateRange({
+ date: plainDateAddDays(date.toPlainDate(), 1),
+ timezoneID: date.timezoneID,
+ });
+ return {
+ label: 'Next day',
+ range: scheduleRangeToZonedDateTimeRange(range, date.timezoneID),
+ };
+ },
+ };
+}
+
+function getDayDateRange({
+ date,
+ timezoneID,
+}: {
+ date: PlainDate;
+ timezoneID: string;
+}) {
+ return getScheduleRangeFromDates({
+ startDate: date,
+ endDate: plainDateAddDays(date, 1),
+ timezoneID,
+ });
+}
diff --git a/packages/lab/src/Schedule/ListView.tsx b/packages/lab/src/Schedule/ListView.tsx
new file mode 100644
index 0000000000..d53ea52940
--- /dev/null
+++ b/packages/lab/src/Schedule/ListView.tsx
@@ -0,0 +1,236 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file ListView.tsx
+ * @input XDSSchedule context and list view options
+ * @output Event-list schedule view factory
+ * @position Concrete schedule view; exported as createXDSScheduleListView
+ */
+
+import * as stylex from '@stylexjs/stylex';
+import {
+ plainDateAddDays,
+ plainDateFromInstant,
+ plainDateIsEqual,
+ plainDateToISO,
+ type PlainDate,
+} from '@xds/core/utils';
+import {XDSHeading} from '@xds/core/Text';
+import {
+ enumerateDates,
+ eventOccursOnDate,
+ getScheduleRangeFromDates,
+ isDayEvent,
+} from './dateMath';
+import {useXDSScheduleContext} from './context';
+import {
+ formatDayNumber,
+ formatFullDate,
+ formatWeekday,
+ formatWeekTitle,
+ isEventInPast,
+ ListEventRow,
+ ScheduleFrame,
+ ScheduleRangeMonthTitle,
+ styles,
+} from './shared';
+import {useCurrentTime} from './useCurrentTime';
+import {scheduleRangeToZonedDateTimeRange} from './zonedDateTime';
+import type {
+ CalendarEvent,
+ Instant,
+ XDSScheduleView,
+ XDSScheduleViewComponentProps,
+} from './types';
+
+export interface XDSScheduleListViewOptions {
+ days?: number;
+}
+
+function XDSScheduleListView(
+ _props: XDSScheduleViewComponentProps<XDSScheduleListViewOptions>,
+) {
+ const {events, timezoneID, range, isLoading} = useXDSScheduleContext();
+ const days = enumerateDates(range.startDate, range.endDate);
+ const currentTime = useCurrentTime();
+ const currentPlainDate = plainDateFromInstant(currentTime, timezoneID);
+ const endDate = plainDateAddDays(range.endDate, -1);
+ const titleLabel = formatWeekTitle(range.startDate, endDate, timezoneID);
+ const visibleDays = days
+ .map(day => {
+ const isCurrentDay = plainDateIsEqual(day, currentPlainDate);
+ const isBaseDay = plainDateIsEqual(day, range.startDate);
+ const dayEvents = events.filter(event =>
+ eventOccursOnDate(event, day, timezoneID),
+ );
+ return {
+ day,
+ dayEvents,
+ isCurrentDay,
+ isVisible: dayEvents.length > 0 || isCurrentDay || isBaseDay,
+ };
+ })
+ .filter(dayRecord => dayRecord.isVisible);
+
+ return (
+ <ScheduleFrame
+ title={
+ <ScheduleRangeMonthTitle
+ start={range.startDate}
+ end={endDate}
+ timezoneID={timezoneID}
+ />
+ }
+ titleLabel={titleLabel}
+ isLoading={isLoading}>
+ <div {...stylex.props(styles.list)}>
+ {visibleDays.map(({day, dayEvents, isCurrentDay}, index) => (
+ <section
+ key={plainDateToISO(day)}
+ {...stylex.props(
+ styles.listDay,
+ index === visibleDays.length - 1 && styles.listDayLast,
+ )}>
+ <ListDayHeading
+ day={day}
+ isCurrentDay={isCurrentDay}
+ timezoneID={timezoneID}
+ />
+ <div {...stylex.props(styles.listEvents)}>
+ {renderListRows({
+ events: dayEvents,
+ timezoneID,
+ showCurrentTime: isCurrentDay && !isLoading,
+ currentTime,
+ })}
+ </div>
+ </section>
+ ))}
+ </div>
+ </ScheduleFrame>
+ );
+}
+
+function ListDayHeading({
+ day,
+ isCurrentDay,
+ timezoneID,
+}: {
+ day: PlainDate;
+ isCurrentDay: boolean;
+ timezoneID: string;
+}) {
+ return (
+ <XDSHeading
+ level={4}
+ color="secondary"
+ display="block"
+ aria-label={formatFullDate(day, timezoneID)}
+ aria-current={isCurrentDay ? 'date' : undefined}
+ xstyle={styles.listDayHeading}>
+ <span
+ {...stylex.props(
+ styles.listDayNumber,
+ isCurrentDay && styles.listDayNumberCurrent,
+ )}>
+ <span {...stylex.props(styles.listDayNumberText)}>
+ {formatDayNumber(day, timezoneID)}
+ </span>
+ </span>
+ {formatWeekday(day, timezoneID, 'short')}
+ </XDSHeading>
+ );
+}
+
+function renderListRows({
+ events,
+ timezoneID,
+ showCurrentTime,
+ currentTime,
+}: {
+ events: ReadonlyArray<CalendarEvent>;
+ timezoneID: string;
+ showCurrentTime: boolean;
+ currentTime: Instant;
+}) {
+ const rows = events.map(event => (
+ <ListEventRow
+ key={event.id}
+ event={event}
+ timezoneID={timezoneID}
+ isPast={isEventInPast(event, currentTime, timezoneID)}
+ />
+ ));
+
+ if (!showCurrentTime) {
+ return rows;
+ }
+
+ const marker = (
+ <div key="current-time" aria-hidden {...stylex.props(styles.listNowRow)} />
+ );
+ const insertIndex = events.findIndex(
+ event => !isDayEvent(event) && event.start > currentTime,
+ );
+ if (insertIndex < 0) {
+ return [...rows, marker];
+ }
+ return [...rows.slice(0, insertIndex), marker, ...rows.slice(insertIndex)];
+}
+
+export function createXDSScheduleListView({
+ days: listDays = 7,
+}: XDSScheduleListViewOptions = {}): XDSScheduleView<XDSScheduleListViewOptions> {
+ return {
+ component: XDSScheduleListView,
+ options: {days: listDays},
+ getDateRange: date => {
+ const range = getListDateRange({
+ date: date.toPlainDate(),
+ timezoneID: date.timezoneID,
+ days: listDays,
+ });
+ return scheduleRangeToZonedDateTimeRange(range, date.timezoneID);
+ },
+ getPreviousDateRange: date => {
+ const range = getListDateRange({
+ date: plainDateAddDays(date.toPlainDate(), -listDays),
+ timezoneID: date.timezoneID,
+ days: listDays,
+ });
+ return {
+ label: 'Previous list range',
+ range: scheduleRangeToZonedDateTimeRange(range, date.timezoneID),
+ };
+ },
+ getNextDateRange: date => {
+ const range = getListDateRange({
+ date: plainDateAddDays(date.toPlainDate(), listDays),
+ timezoneID: date.timezoneID,
+ days: listDays,
+ });
+ return {
+ label: 'Next list range',
+ range: scheduleRangeToZonedDateTimeRange(range, date.timezoneID),
+ };
+ },
+ };
+}
+
+function getListDateRange({
+ date,
+ timezoneID,
+ days,
+}: {
+ date: PlainDate;
+ timezoneID: string;
+ days: number;
+}) {
+ return getScheduleRangeFromDates({
+ startDate: date,
+ endDate: plainDateAddDays(date, days),
+ timezoneID,
+ });
+}
diff --git a/packages/lab/src/Schedule/MonthlyView.tsx b/packages/lab/src/Schedule/MonthlyView.tsx
new file mode 100644
index 0000000000..0bc0cac152
--- /dev/null
+++ b/packages/lab/src/Schedule/MonthlyView.tsx
@@ -0,0 +1,401 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file MonthlyView.tsx
+ * @input XDSSchedule context and monthly view options
+ * @output Month grid schedule view factory
+ * @position Concrete schedule view; exported as createXDSScheduleMonthlyView
+ */
+
+import * as stylex from '@stylexjs/stylex';
+import {
+ plainDateAddDays,
+ plainDateAddMonths,
+ plainDateFromInstant,
+ plainDateIsAfter,
+ plainDateIsBefore,
+ plainDateIsEqual,
+ plainDateSetEndOfWeekExclusive,
+ plainDateSetFirstOfMonth,
+ plainDateSetStartOfWeek,
+ plainDateToISO,
+ type PlainDate,
+} from '@xds/core/utils';
+import {XDSHeading, XDSText} from '@xds/core/Text';
+import {
+ enumerateDates,
+ getScheduleRangeFromDates,
+ isDayEvent,
+} from './dateMath';
+import {useXDSScheduleContext} from './context';
+import {
+ formatDayNumber,
+ formatEventAccessibilityLabel,
+ formatFullDate,
+ formatMonthTitle,
+ formatWeekday,
+ isEventInPast,
+ MonthEventPill,
+ ScheduleFrame,
+ ScheduleMonthTitle,
+ styles,
+} from './shared';
+import {useCurrentTime} from './useCurrentTime';
+import {scheduleRangeToZonedDateTimeRange} from './zonedDateTime';
+import type {
+ CalendarEvent,
+ XDSScheduleView,
+ XDSScheduleViewComponentProps,
+} from './types';
+
+export interface XDSScheduleMonthlyViewOptions {
+ weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
+}
+
+function XDSScheduleMonthlyView(
+ _props: XDSScheduleViewComponentProps<XDSScheduleMonthlyViewOptions>,
+) {
+ const {events, categories, date, focusDate, timezoneID, range, isLoading} =
+ useXDSScheduleContext();
+ const rangeDate = date.toPlainDate();
+ const highlightedDate = focusDate.toPlainDate();
+ const currentTime = useCurrentTime();
+ const days = enumerateDates(range.startDate, range.endDate);
+ const weeks = getWeeks(days);
+ const eventSegments = getMonthEventSegments(events, days, timezoneID);
+ const eventsByDay = getMonthEventsByDay(events, days, timezoneID);
+
+ return (
+ <ScheduleFrame
+ title={<ScheduleMonthTitle date={rangeDate} timezoneID={timezoneID} />}
+ titleLabel={formatMonthTitle(rangeDate, timezoneID)}
+ isLoading={isLoading}>
+ <div
+ role="grid"
+ aria-label={formatMonthTitle(rangeDate, timezoneID)}
+ aria-readonly
+ {...stylex.props(styles.monthGrid)}>
+ <div role="row" {...stylex.props(styles.weekHeader)}>
+ {days.slice(0, 7).map((day, index) => (
+ <div
+ key={plainDateToISO(day)}
+ role="columnheader"
+ aria-label={formatWeekday(day, timezoneID, 'long')}
+ aria-colindex={index + 1}
+ {...stylex.props(styles.weekdayLabel)}>
+ <XDSHeading
+ level={4}
+ color="secondary"
+ display="block"
+ xstyle={styles.weekdayHeading}>
+ {formatWeekday(day, timezoneID, 'short')}
+ </XDSHeading>
+ </div>
+ ))}
+ </div>
+ <div {...stylex.props(styles.monthGridSurface)}>
+ <div {...stylex.props(styles.monthCellGrid)}>
+ {weeks.map((week, weekIndex) => (
+ <div
+ key={plainDateToISO(week[0])}
+ role="row"
+ {...stylex.props(styles.monthGridRow)}>
+ {week.map((day, dayIndex) => {
+ const index = weekIndex * 7 + dayIndex;
+ const isOutsideMonth = day.month !== rangeDate.month;
+ const dayEvents =
+ eventsByDay.get(plainDateToISO(day)) ?? EMPTY_EVENTS;
+ return (
+ <div
+ key={plainDateToISO(day)}
+ role="gridcell"
+ aria-label={formatFullDate(day, timezoneID)}
+ aria-colindex={dayIndex + 1}
+ aria-current={
+ plainDateIsEqual(day, highlightedDate)
+ ? 'date'
+ : undefined
+ }
+ {...stylex.props(
+ styles.monthCell,
+ index % 7 === 6 && styles.monthCellLastColumn,
+ index >= days.length - 7 && styles.monthCellLastRow,
+ isOutsideMonth && styles.monthCellOutside,
+ )}>
+ <div
+ {...stylex.props(
+ styles.monthDayNumber,
+ plainDateIsEqual(day, highlightedDate) &&
+ styles.currentDayPill,
+ )}>
+ <XDSText
+ type="supporting"
+ color="inherit"
+ weight="medium"
+ hasTabularNumbers>
+ {formatDayNumber(day, timezoneID)}
+ </XDSText>
+ </div>
+ {dayEvents.length > 0 && (
+ <ul {...stylex.props(styles.visuallyHidden)}>
+ {dayEvents.map(event => (
+ <li key={event.id}>
+ {formatEventAccessibilityLabel(
+ event,
+ day,
+ timezoneID,
+ categories,
+ )}
+ </li>
+ ))}
+ </ul>
+ )}
+ </div>
+ );
+ })}
+ </div>
+ ))}
+ </div>
+ <div aria-hidden {...stylex.props(styles.monthEventOverlay)}>
+ {eventSegments.map(segment => (
+ <div
+ key={`${segment.event.id}:${segment.week}:${segment.columnStart}`}
+ {...stylex.props(
+ styles.monthEventSpan(
+ segment.week,
+ segment.columnStart,
+ segment.columnEnd,
+ segment.level,
+ ),
+ )}>
+ <MonthEventPill
+ event={segment.event}
+ timezoneID={timezoneID}
+ isPast={isEventInPast(segment.event, currentTime, timezoneID)}
+ />
+ </div>
+ ))}
+ </div>
+ </div>
+ </div>
+ </ScheduleFrame>
+ );
+}
+
+function getWeeks(days: ReadonlyArray<PlainDate>): PlainDate[][] {
+ const weeks: PlainDate[][] = [];
+ for (let index = 0; index < days.length; index += 7) {
+ weeks.push(days.slice(index, index + 7));
+ }
+ return weeks;
+}
+
+const EMPTY_EVENTS: ReadonlyArray<CalendarEvent> = [];
+
+function getMonthEventsByDay(
+ events: ReadonlyArray<CalendarEvent>,
+ days: ReadonlyArray<PlainDate>,
+ timezoneID: string,
+): Map<string, CalendarEvent[]> {
+ const eventsByDay = new Map<string, CalendarEvent[]>();
+ days.forEach(day => {
+ eventsByDay.set(plainDateToISO(day), []);
+ });
+ const firstDay = days[0];
+ const lastDay = days[days.length - 1];
+ if (firstDay == null || lastDay == null) {
+ return eventsByDay;
+ }
+
+ events.forEach(event => {
+ const [eventStart, eventEnd] = getEventDateSpan(event, timezoneID);
+ if (
+ plainDateIsBefore(eventEnd, firstDay) ||
+ plainDateIsAfter(eventStart, lastDay)
+ ) {
+ return;
+ }
+
+ let current = plainDateIsBefore(eventStart, firstDay)
+ ? firstDay
+ : eventStart;
+ const visibleEnd = plainDateIsAfter(eventEnd, lastDay) ? lastDay : eventEnd;
+ while (!plainDateIsAfter(current, visibleEnd)) {
+ eventsByDay.get(plainDateToISO(current))?.push(event);
+ current = plainDateAddDays(current, 1);
+ }
+ });
+
+ return eventsByDay;
+}
+
+interface MonthEventSegment {
+ event: CalendarEvent;
+ week: number;
+ columnStart: number;
+ columnEnd: number;
+ level: number;
+}
+
+const MAX_MONTH_EVENT_LEVELS = 4;
+
+function getMonthEventSegments(
+ events: ReadonlyArray<CalendarEvent>,
+ days: ReadonlyArray<PlainDate>,
+ timezoneID: string,
+): MonthEventSegment[] {
+ const segments: MonthEventSegment[] = [];
+ const levelsByWeek: Array<number[]> = [];
+ const monthEvents = events
+ .map(event => {
+ const [eventStart, eventEnd] = getEventDateSpan(event, timezoneID);
+ const startIndex = days.findIndex(
+ day => !plainDateIsBefore(day, eventStart),
+ );
+ const endIndexFromRight = [...days]
+ .reverse()
+ .findIndex(day => !plainDateIsAfter(day, eventEnd));
+ if (startIndex < 0 || endIndexFromRight < 0) {
+ return null;
+ }
+ const endIndex = days.length - 1 - endIndexFromRight;
+ return {
+ event,
+ startIndex,
+ endIndex,
+ isPriority: isDayEvent(event) || endIndex > startIndex,
+ };
+ })
+ .filter(
+ (
+ record,
+ ): record is {
+ event: CalendarEvent;
+ startIndex: number;
+ endIndex: number;
+ isPriority: boolean;
+ } => record != null,
+ )
+ .sort((a, b) => {
+ if (a.startIndex !== b.startIndex) {
+ return a.startIndex - b.startIndex;
+ }
+ if (a.isPriority !== b.isPriority) {
+ return a.isPriority ? -1 : 1;
+ }
+ const aDuration = a.endIndex - a.startIndex;
+ const bDuration = b.endIndex - b.startIndex;
+ if (aDuration !== bDuration) {
+ return bDuration - aDuration;
+ }
+ return a.event.title.localeCompare(b.event.title);
+ });
+
+ monthEvents.forEach(({event, startIndex, endIndex}) => {
+ const [eventStart, eventEnd] = getEventDateSpan(event, timezoneID);
+ if (
+ plainDateIsBefore(eventEnd, days[0]) ||
+ plainDateIsAfter(eventStart, days[days.length - 1])
+ ) {
+ return;
+ }
+
+ for (
+ let week = Math.floor(startIndex / 7);
+ week <= Math.floor(endIndex / 7);
+ week += 1
+ ) {
+ const columnStart =
+ week === Math.floor(startIndex / 7) ? startIndex % 7 : 0;
+ const columnEnd = week === Math.floor(endIndex / 7) ? endIndex % 7 : 6;
+ const weekLevels = (levelsByWeek[week] ??= []);
+ const level = getAvailableLevel(weekLevels, columnStart);
+ if (level < MAX_MONTH_EVENT_LEVELS) {
+ weekLevels[level] = columnEnd;
+ segments.push({event, week, columnStart, columnEnd, level});
+ }
+ }
+ });
+
+ return segments;
+}
+
+function getEventDateSpan(
+ event: CalendarEvent,
+ timezoneID: string,
+): [PlainDate, PlainDate] {
+ if (isDayEvent(event)) {
+ return [event.start, event.end];
+ }
+ return [
+ plainDateFromInstant(event.start, timezoneID),
+ plainDateFromInstant(Math.max(event.end - 1, event.start), timezoneID),
+ ];
+}
+
+function getAvailableLevel(levels: number[], columnStart: number): number {
+ const level = levels.findIndex(columnEnd => columnStart > columnEnd);
+ return level >= 0 ? level : levels.length;
+}
+
+export function createXDSScheduleMonthlyView({
+ weekStartsOn = 0,
+}: XDSScheduleMonthlyViewOptions = {}): XDSScheduleView<XDSScheduleMonthlyViewOptions> {
+ return {
+ component: XDSScheduleMonthlyView,
+ options: {weekStartsOn},
+ getDateRange: date => {
+ const range = getMonthDateRange({
+ date: date.toPlainDate(),
+ timezoneID: date.timezoneID,
+ weekStartsOn,
+ });
+ return scheduleRangeToZonedDateTimeRange(range, date.timezoneID);
+ },
+ getPreviousDateRange: date => {
+ const range = getMonthDateRange({
+ date: plainDateAddMonths(date.toPlainDate(), -1),
+ timezoneID: date.timezoneID,
+ weekStartsOn,
+ });
+ return {
+ label: 'Previous month',
+ range: scheduleRangeToZonedDateTimeRange(range, date.timezoneID),
+ };
+ },
+ getNextDateRange: date => {
+ const range = getMonthDateRange({
+ date: plainDateAddMonths(date.toPlainDate(), 1),
+ timezoneID: date.timezoneID,
+ weekStartsOn,
+ });
+ return {
+ label: 'Next month',
+ range: scheduleRangeToZonedDateTimeRange(range, date.timezoneID),
+ };
+ },
+ };
+}
+
+function getMonthDateRange({
+ date,
+ timezoneID,
+ weekStartsOn,
+}: {
+ date: PlainDate;
+ timezoneID: string;
+ weekStartsOn: number;
+}) {
+ const firstOfMonth = plainDateSetFirstOfMonth(date);
+ const nextMonth = plainDateAddMonths(firstOfMonth, 1);
+ return getScheduleRangeFromDates({
+ startDate: plainDateSetStartOfWeek(firstOfMonth, weekStartsOn),
+ endDate: plainDateSetEndOfWeekExclusive(
+ plainDateAddDays(nextMonth, -1),
+ weekStartsOn,
+ ),
+ timezoneID,
+ });
+}
diff --git a/packages/lab/src/Schedule/TimeGridView.tsx b/packages/lab/src/Schedule/TimeGridView.tsx
new file mode 100644
index 0000000000..e62b2e81e0
--- /dev/null
+++ b/packages/lab/src/Schedule/TimeGridView.tsx
@@ -0,0 +1,589 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file TimeGridView.tsx
+ * @input Schedule context, visible days, timezone, and hour bounds
+ * @output Shared weekly/day time-grid layout
+ * @position Internal view primitive shared by WeeklyView and DayView
+ */
+
+import * as stylex from '@stylexjs/stylex';
+import {
+ plainDateAddDays,
+ plainDateFromInstant,
+ plainDateIsBefore,
+ plainDateIsEqual,
+ plainDateToInstant,
+ plainDateToISO,
+ type PlainDate,
+} from '@xds/core/utils';
+import {XDSHeading, XDSText} from '@xds/core/Text';
+import {useXDSScheduleContext} from './context';
+import {eventOccursOnDate, isDayEvent} from './dateMath';
+import {
+ clamp,
+ EventPill,
+ eventPastSurfaceColorStyle,
+ eventSurfaceColorStyle,
+ eventSpansPastDay,
+ formatEventAccessibilityLabel,
+ formatDayNumber,
+ formatEventTime,
+ formatFullDate,
+ formatHour,
+ formatTimezoneAbbreviation,
+ formatWeekday,
+ getEventCategory,
+ getMinutesSinceStartOfDay,
+ isEventInPast,
+ styles,
+} from './shared';
+import {useCurrentTime} from './useCurrentTime';
+import type {
+ CalendarDayEvent,
+ CalendarEvent,
+ CalendarInstantEvent,
+ XDSScheduleCategory,
+} from './types';
+
+export function TimeGridView({
+ days,
+ events,
+ focusDate,
+ timezoneID,
+ minHour,
+ maxHour,
+ hourHeight,
+}: {
+ days: PlainDate[];
+ events: ReadonlyArray<CalendarEvent>;
+ focusDate: PlainDate;
+ timezoneID: string;
+ minHour: number;
+ maxHour: number;
+ hourHeight: number;
+}) {
+ const {categories} = useXDSScheduleContext();
+ const normalizedMinHour = Math.max(0, Math.min(23, Math.floor(minHour)));
+ const normalizedMaxHour = Math.max(
+ normalizedMinHour + 1,
+ Math.min(24, Math.floor(maxHour)),
+ );
+ const hours = Array.from(
+ {length: normalizedMaxHour - normalizedMinHour},
+ (_, index) => normalizedMinHour + index,
+ );
+ const allDayEvents = events.filter(isDayEvent);
+ const allDaySegments = getAllDayEventSegments(allDayEvents, days);
+ const allDayLevelCount = allDaySegments.reduce(
+ (levelCount, segment) => Math.max(levelCount, segment.level + 1),
+ 0,
+ );
+ const instantEvents = events.filter(
+ (event): event is CalendarInstantEvent => !isDayEvent(event),
+ );
+ const currentTime = useCurrentTime();
+ const currentDate = plainDateFromInstant(currentTime, timezoneID);
+ const timezoneLabel = formatTimezoneAbbreviation(
+ days[0] ?? focusDate,
+ timezoneID,
+ );
+
+ return (
+ <>
+ <TimeGridAccessibilityGrid
+ allDayEvents={allDayEvents}
+ categories={categories}
+ days={days}
+ events={instantEvents}
+ focusDate={focusDate}
+ hours={hours}
+ timezoneID={timezoneID}
+ timezoneLabel={timezoneLabel}
+ />
+ <div aria-hidden {...stylex.props(styles.timeGrid)}>
+ <div {...stylex.props(styles.timeGridCorner)} />
+ <div {...stylex.props(styles.timeGridHeader)}>
+ {days.map((day, index) => (
+ <div
+ key={plainDateToISO(day)}
+ {...stylex.props(
+ styles.timeGridHeaderCell,
+ index === days.length - 1 && styles.timeGridHeaderCellLast,
+ )}>
+ <XDSHeading
+ level={4}
+ color="secondary"
+ display="block"
+ xstyle={styles.timeGridHeaderHeading}>
+ <span {...stylex.props(styles.timeGridHeaderHeadingContent)}>
+ {formatWeekday(day, timezoneID, 'short')}
+ <span
+ {...stylex.props(
+ styles.timeGridDayNumber,
+ plainDateIsEqual(day, focusDate) &&
+ styles.timeGridCurrentDayPill,
+ )}>
+ {formatDayNumber(day, timezoneID)}
+ </span>
+ </span>
+ </XDSHeading>
+ </div>
+ ))}
+ </div>
+ <div {...stylex.props(styles.allDayLabel)}>
+ <XDSText type="supporting" color="secondary" weight="bold">
+ {timezoneLabel}
+ </XDSText>
+ </div>
+ <div {...stylex.props(styles.allDayRow)}>
+ <div
+ {...stylex.props(
+ styles.allDayRowSurface(days.length, allDayLevelCount),
+ )}>
+ <div {...stylex.props(styles.allDayCellGrid(days.length))}>
+ {days.map((day, index) => (
+ <div
+ key={plainDateToISO(day)}
+ {...stylex.props(
+ styles.allDayCell,
+ index === days.length - 1 && styles.allDayCellLast,
+ )}
+ />
+ ))}
+ </div>
+ <div {...stylex.props(styles.allDayEventOverlay(days.length))}>
+ {allDaySegments.map(segment => (
+ <div
+ key={`${segment.event.id}:${segment.columnStart}`}
+ {...stylex.props(
+ styles.allDayEventSpan(
+ segment.columnStart,
+ segment.columnEnd,
+ segment.level,
+ ),
+ )}>
+ <EventPill
+ event={segment.event}
+ isPast={isEventInPast(
+ segment.event,
+ currentTime,
+ timezoneID,
+ )}
+ />
+ </div>
+ ))}
+ </div>
+ </div>
+ </div>
+ <div {...stylex.props(styles.timeGridBody)}>
+ <div {...stylex.props(styles.timeLabels)}>
+ {hours.slice(1).map((hour, index) => (
+ <div
+ key={hour}
+ {...stylex.props(
+ styles.timeLabel,
+ styles.timeLabelPosition(index + 1, hourHeight),
+ )}>
+ {formatHour(hour)}
+ </div>
+ ))}
+ </div>
+ <div {...stylex.props(styles.timeColumns)}>
+ {days.map((day, index) => {
+ const currentTimeTop = getCurrentTimeTop({
+ currentTime,
+ day,
+ timezoneID,
+ minHour: normalizedMinHour,
+ maxHour: normalizedMaxHour,
+ });
+ return (
+ <div
+ key={plainDateToISO(day)}
+ {...stylex.props(
+ styles.timeColumn,
+ styles.timeColumnRows(hourHeight),
+ index === days.length - 1 && styles.timeColumnLast,
+ )}>
+ {hours.map((hour, index) => (
+ <div
+ key={hour}
+ {...stylex.props(
+ styles.hourSlot,
+ index === hours.length - 1 && styles.hourSlotLast,
+ )}
+ />
+ ))}
+ {getTimedEventLayouts({
+ events: instantEvents.filter(event =>
+ eventOccursOnDate(event, day, timezoneID),
+ ),
+ day,
+ timezoneID,
+ minHour: normalizedMinHour,
+ maxHour: normalizedMaxHour,
+ }).map(({event, height, level, top}) => {
+ const timeLabel = formatEventTime(event, day, timezoneID);
+ const category = getEventCategory(event, categories);
+ return (
+ <div
+ key={event.id}
+ {...stylex.props(
+ styles.timedEvent,
+ styles.timedEventPosition(
+ clamp(top, 0, 100),
+ clamp(height, 4, 100),
+ level,
+ ),
+ isEventInPast(event, currentTime, timezoneID)
+ ? eventPastSurfaceColorStyle(category.color)
+ : eventSurfaceColorStyle(category.color),
+ )}>
+ <XDSText
+ type="supporting"
+ color="inherit"
+ weight="bold"
+ xstyle={styles.eventTitle}>
+ {event.title}
+ </XDSText>
+ <XDSText
+ type="supporting"
+ color="inherit"
+ xstyle={styles.eventTime}>
+ {timeLabel}
+ </XDSText>
+ </div>
+ );
+ })}
+ {plainDateIsEqual(day, currentDate) &&
+ currentTimeTop != null && (
+ <div
+ aria-hidden
+ {...stylex.props(
+ styles.currentTimeLine(currentTimeTop),
+ )}
+ />
+ )}
+ </div>
+ );
+ })}
+ </div>
+ </div>
+ </div>
+ </>
+ );
+}
+
+function TimeGridAccessibilityGrid({
+ allDayEvents,
+ categories,
+ days,
+ events,
+ focusDate,
+ hours,
+ timezoneID,
+ timezoneLabel,
+}: {
+ allDayEvents: ReadonlyArray<CalendarDayEvent>;
+ categories: ReadonlyArray<XDSScheduleCategory>;
+ days: ReadonlyArray<PlainDate>;
+ events: ReadonlyArray<CalendarInstantEvent>;
+ focusDate: PlainDate;
+ hours: ReadonlyArray<number>;
+ timezoneID: string;
+ timezoneLabel: string;
+}) {
+ return (
+ <div
+ role="grid"
+ aria-label="Schedule time grid"
+ aria-readonly
+ {...stylex.props(styles.visuallyHidden)}>
+ <div role="row">
+ <div role="columnheader" aria-colindex={1}>
+ Time
+ </div>
+ {days.map((day, index) => (
+ <div
+ key={plainDateToISO(day)}
+ role="columnheader"
+ aria-colindex={index + 2}
+ aria-current={
+ plainDateIsEqual(day, focusDate) ? 'date' : undefined
+ }>
+ {formatFullDate(day, timezoneID)}
+ </div>
+ ))}
+ </div>
+ <div role="row">
+ <div role="rowheader" aria-colindex={1}>
+ {timezoneLabel} all day
+ </div>
+ {days.map((day, index) => {
+ const cellEvents = allDayEvents.filter(event =>
+ eventOccursOnDate(event, day, timezoneID),
+ );
+ return (
+ <div
+ key={plainDateToISO(day)}
+ role="gridcell"
+ aria-colindex={index + 2}
+ aria-label={formatTimeGridAccessibilityCellLabel({
+ categories,
+ day,
+ events: cellEvents,
+ label: `${formatFullDate(day, timezoneID)} all day`,
+ timezoneID,
+ })}
+ />
+ );
+ })}
+ </div>
+ {hours.map(hour => (
+ <div key={hour} role="row">
+ <div role="rowheader" aria-colindex={1}>
+ {formatHour(hour)}
+ </div>
+ {days.map((day, index) => {
+ const cellEvents = events.filter(event =>
+ eventOverlapsHour(event, day, hour, timezoneID),
+ );
+ return (
+ <div
+ key={plainDateToISO(day)}
+ role="gridcell"
+ aria-colindex={index + 2}
+ aria-label={formatTimeGridAccessibilityCellLabel({
+ categories,
+ day,
+ events: cellEvents,
+ label: `${formatFullDate(day, timezoneID)} ${formatHour(
+ hour,
+ )}`,
+ timezoneID,
+ })}
+ />
+ );
+ })}
+ </div>
+ ))}
+ </div>
+ );
+}
+
+function formatTimeGridAccessibilityCellLabel({
+ categories,
+ day,
+ events,
+ label,
+ timezoneID,
+}: {
+ categories: ReadonlyArray<XDSScheduleCategory>;
+ day: PlainDate;
+ events: ReadonlyArray<CalendarEvent>;
+ label: string;
+ timezoneID: string;
+}): string {
+ if (events.length === 0) {
+ return label;
+ }
+ const eventLabels = events.map(event =>
+ formatEventAccessibilityLabel(event, day, timezoneID, categories),
+ );
+ return `${label}. ${eventLabels.join('. ')}`;
+}
+
+function eventOverlapsHour(
+ event: CalendarInstantEvent,
+ day: PlainDate,
+ hour: number,
+ timezoneID: string,
+): boolean {
+ if (!eventOccursOnDate(event, day, timezoneID)) {
+ return false;
+ }
+ const hourStart = plainDateToInstant(day, timezoneID, hour);
+ const hourEnd =
+ hour === 23
+ ? plainDateToInstant(plainDateAddDays(day, 1), timezoneID)
+ : plainDateToInstant(day, timezoneID, hour + 1);
+ return event.start < hourEnd && event.end > hourStart;
+}
+
+interface AllDayEventSegment {
+ event: CalendarDayEvent;
+ columnStart: number;
+ columnEnd: number;
+ level: number;
+}
+
+function getAllDayEventSegments(
+ events: ReadonlyArray<CalendarDayEvent>,
+ days: ReadonlyArray<PlainDate>,
+): AllDayEventSegment[] {
+ const levels: number[] = [];
+ return events
+ .map(event => {
+ const startIndex = days.findIndex(
+ day => !plainDateIsBefore(day, event.start),
+ );
+ const endIndexFromRight = [...days]
+ .reverse()
+ .findIndex(day => !plainDateIsBefore(event.end, day));
+ if (startIndex < 0 || endIndexFromRight < 0) {
+ return null;
+ }
+ const endIndex = days.length - 1 - endIndexFromRight;
+ return {event, startIndex, endIndex};
+ })
+ .filter(
+ (
+ segment,
+ ): segment is {
+ event: CalendarDayEvent;
+ startIndex: number;
+ endIndex: number;
+ } => segment != null,
+ )
+ .sort((a, b) => {
+ if (a.startIndex !== b.startIndex) {
+ return a.startIndex - b.startIndex;
+ }
+ const aDuration = a.endIndex - a.startIndex;
+ const bDuration = b.endIndex - b.startIndex;
+ return (
+ bDuration - aDuration || a.event.title.localeCompare(b.event.title)
+ );
+ })
+ .map(({event, startIndex, endIndex}) => {
+ const level = getAvailableAllDayLevel(levels, startIndex);
+ levels[level] = endIndex;
+ return {
+ event,
+ columnStart: startIndex,
+ columnEnd: endIndex,
+ level,
+ };
+ });
+}
+
+function getAvailableAllDayLevel(
+ levels: number[],
+ columnStart: number,
+): number {
+ const level = levels.findIndex(columnEnd => columnStart > columnEnd);
+ return level >= 0 ? level : levels.length;
+}
+
+interface TimedEventLayout {
+ event: CalendarInstantEvent;
+ top: number;
+ height: number;
+ level: number;
+}
+
+function getTimedEventLayouts({
+ events,
+ day,
+ timezoneID,
+ minHour,
+ maxHour,
+}: {
+ events: ReadonlyArray<CalendarInstantEvent>;
+ day: PlainDate;
+ timezoneID: string;
+ minHour: number;
+ maxHour: number;
+}): TimedEventLayout[] {
+ const totalMinutes = (maxHour - minHour) * 60;
+ const levelEndMinutes: number[] = [];
+
+ return events
+ .map(event => {
+ const startDate = plainDateFromInstant(event.start, timezoneID);
+ const rawStart = plainDateIsBefore(startDate, day)
+ ? 0
+ : getMinutesSinceStartOfDay(event.start, timezoneID);
+ const rawEnd = eventSpansPastDay(event, day, timezoneID)
+ ? 24 * 60
+ : getMinutesSinceStartOfDay(event.end, timezoneID);
+ const minMinute = minHour * 60;
+ const maxMinute = maxHour * 60;
+ if (rawEnd <= minMinute || rawStart >= maxMinute) {
+ return null;
+ }
+ const visibleStart = Math.max(rawStart, minMinute);
+ const visibleEnd = Math.min(
+ maxMinute,
+ Math.max(visibleStart + 15, rawEnd),
+ );
+ return {event, visibleStart, visibleEnd};
+ })
+ .filter(
+ (
+ layout,
+ ): layout is {
+ event: CalendarInstantEvent;
+ visibleStart: number;
+ visibleEnd: number;
+ } => layout != null && layout.visibleEnd > layout.visibleStart,
+ )
+ .sort((a, b) => {
+ if (a.visibleStart !== b.visibleStart) {
+ return a.visibleStart - b.visibleStart;
+ }
+ return (
+ a.visibleEnd - b.visibleEnd ||
+ a.event.title.localeCompare(b.event.title)
+ );
+ })
+ .map(({event, visibleEnd, visibleStart}) => {
+ const level = getAvailableTimedEventLevel(levelEndMinutes, visibleStart);
+ levelEndMinutes[level] = visibleEnd;
+ return {
+ event,
+ level,
+ top: ((visibleStart - minHour * 60) / totalMinutes) * 100,
+ height: ((visibleEnd - visibleStart) / totalMinutes) * 100,
+ };
+ });
+}
+
+function getAvailableTimedEventLevel(
+ levelEndMinutes: number[],
+ visibleStart: number,
+): number {
+ const level = levelEndMinutes.findIndex(
+ endMinute => visibleStart >= endMinute,
+ );
+ return level >= 0 ? level : levelEndMinutes.length;
+}
+
+function getCurrentTimeTop({
+ currentTime,
+ day,
+ timezoneID,
+ minHour,
+ maxHour,
+}: {
+ currentTime: number;
+ day: PlainDate;
+ timezoneID: string;
+ minHour: number;
+ maxHour: number;
+}): number | null {
+ const currentDate = plainDateFromInstant(currentTime, timezoneID);
+ if (!plainDateIsEqual(day, currentDate)) {
+ return null;
+ }
+ const currentMinute = getMinutesSinceStartOfDay(currentTime, timezoneID);
+ const minMinute = minHour * 60;
+ const maxMinute = maxHour * 60;
+ if (currentMinute < minMinute || currentMinute > maxMinute) {
+ return null;
+ }
+ return ((currentMinute - minMinute) / (maxMinute - minMinute)) * 100;
+}
diff --git a/packages/lab/src/Schedule/WeeklyView.tsx b/packages/lab/src/Schedule/WeeklyView.tsx
new file mode 100644
index 0000000000..05cf2614c8
--- /dev/null
+++ b/packages/lab/src/Schedule/WeeklyView.tsx
@@ -0,0 +1,130 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file WeeklyView.tsx
+ * @input XDSSchedule context and weekly view options
+ * @output Week time-grid schedule view factory
+ * @position Concrete schedule view; exported as createXDSScheduleWeeklyView
+ */
+
+import {plainDateAddDays, plainDateSetStartOfWeek} from '@xds/core/utils';
+import {enumerateDates, getScheduleRangeFromDates} from './dateMath';
+import {useXDSScheduleContext} from './context';
+import {
+ formatWeekTitle,
+ ScheduleFrame,
+ ScheduleRangeMonthTitle,
+} from './shared';
+import {TimeGridView} from './TimeGridView';
+import {scheduleRangeToZonedDateTimeRange} from './zonedDateTime';
+import type {
+ PlainDate,
+ XDSScheduleView,
+ XDSScheduleViewComponentProps,
+} from './types';
+
+export interface XDSScheduleWeeklyViewOptions {
+ weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
+ minHour?: number;
+ maxHour?: number;
+ hourHeight?: number;
+}
+
+function XDSScheduleWeeklyView({
+ options,
+}: XDSScheduleViewComponentProps<XDSScheduleWeeklyViewOptions>) {
+ const {events, focusDate, timezoneID, range, isLoading} =
+ useXDSScheduleContext();
+ const {minHour = 0, maxHour = 24, hourHeight = 100} = options;
+ const days = enumerateDates(range.startDate, range.endDate);
+ const highlightedDate = focusDate.toPlainDate();
+ const titleLabel = formatWeekTitle(
+ days[0],
+ days[days.length - 1],
+ timezoneID,
+ );
+
+ return (
+ <ScheduleFrame
+ title={
+ <ScheduleRangeMonthTitle
+ start={days[0]}
+ end={days[days.length - 1]}
+ timezoneID={timezoneID}
+ />
+ }
+ titleLabel={titleLabel}
+ isLoading={isLoading}>
+ <TimeGridView
+ days={days}
+ events={events}
+ focusDate={highlightedDate}
+ timezoneID={timezoneID}
+ minHour={minHour}
+ maxHour={maxHour}
+ hourHeight={hourHeight}
+ />
+ </ScheduleFrame>
+ );
+}
+
+export function createXDSScheduleWeeklyView({
+ weekStartsOn = 0,
+ minHour = 0,
+ maxHour = 24,
+ hourHeight = 100,
+}: XDSScheduleWeeklyViewOptions = {}): XDSScheduleView<XDSScheduleWeeklyViewOptions> {
+ return {
+ component: XDSScheduleWeeklyView,
+ options: {weekStartsOn, minHour, maxHour, hourHeight},
+ getDateRange: date => {
+ const range = getWeekDateRange({
+ date: date.toPlainDate(),
+ timezoneID: date.timezoneID,
+ weekStartsOn,
+ });
+ return scheduleRangeToZonedDateTimeRange(range, date.timezoneID);
+ },
+ getPreviousDateRange: date => {
+ const range = getWeekDateRange({
+ date: plainDateAddDays(date.toPlainDate(), -7),
+ timezoneID: date.timezoneID,
+ weekStartsOn,
+ });
+ return {
+ label: 'Previous week',
+ range: scheduleRangeToZonedDateTimeRange(range, date.timezoneID),
+ };
+ },
+ getNextDateRange: date => {
+ const range = getWeekDateRange({
+ date: plainDateAddDays(date.toPlainDate(), 7),
+ timezoneID: date.timezoneID,
+ weekStartsOn,
+ });
+ return {
+ label: 'Next week',
+ range: scheduleRangeToZonedDateTimeRange(range, date.timezoneID),
+ };
+ },
+ };
+}
+
+function getWeekDateRange({
+ date,
+ timezoneID,
+ weekStartsOn,
+}: {
+ date: PlainDate;
+ timezoneID: string;
+ weekStartsOn: number;
+}) {
+ const startDate = plainDateSetStartOfWeek(date, weekStartsOn);
+ return getScheduleRangeFromDates({
+ startDate,
+ endDate: plainDateAddDays(startDate, 7),
+ timezoneID,
+ });
+}
diff --git a/packages/lab/src/Schedule/XDSSchedule.test.tsx b/packages/lab/src/Schedule/XDSSchedule.test.tsx
new file mode 100644
index 0000000000..d4b34e222b
--- /dev/null
+++ b/packages/lab/src/Schedule/XDSSchedule.test.tsx
@@ -0,0 +1,404 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {fireEvent, render, screen, waitFor} from '@testing-library/react';
+import {createEventFromISO} from './CalendarEvent';
+import {XDSSchedule} from './XDSSchedule';
+import {createXDSScheduleDayView} from './DayView';
+import {createXDSScheduleListView} from './ListView';
+import {createXDSScheduleMonthlyView} from './MonthlyView';
+import {createXDSScheduleWeeklyView} from './WeeklyView';
+import {sortEvents} from './dateMath';
+import {useXDSScheduleViewSelectorPlugin} from './plugins/ViewSelectorPlugin';
+import type {
+ CalendarEvent,
+ Instant,
+ XDSScheduleCategory,
+ XDSSchedulePlugin,
+} from './types';
+
+describe('createEventFromISO', () => {
+ it('creates all-day PlainDate events from date-only ISO strings', () => {
+ const event = createEventFromISO({
+ id: 'planning',
+ title: 'Planning offsite',
+ category: 'Planning',
+ start: '2026-05-13',
+ end: '2026-05-14',
+ });
+
+ expect(event).toEqual({
+ id: 'planning',
+ title: 'Planning offsite',
+ category: 'Planning',
+ start: {year: 2026, month: 5, day: 13},
+ end: {year: 2026, month: 5, day: 14},
+ });
+ });
+
+ it('creates instant events from date-time ISO strings', () => {
+ const event = createEventFromISO({
+ id: 'standup',
+ title: 'Standup',
+ start: '2026-05-13T16:00:00.000Z',
+ end: '2026-05-13T16:30:00.000Z',
+ });
+
+ expect(typeof event.start).toBe('number');
+ expect(event.start).toBe(Date.parse('2026-05-13T16:00:00.000Z'));
+ });
+});
+
+describe('XDSSchedule', () => {
+ const categories: XDSScheduleCategory[] = [
+ {label: 'Sync', color: 'blue'},
+ {label: 'Design', color: 'purple'},
+ {label: 'Blocked', color: 'red'},
+ {label: 'Migration', color: 'pink'},
+ ];
+ const events: CalendarEvent[] = [
+ createEventFromISO({
+ id: 'visible',
+ title: 'Visible sync',
+ category: 'Sync',
+ start: '2026-05-13T16:00:00.000Z',
+ end: '2026-05-13T16:30:00.000Z',
+ }),
+ createEventFromISO({
+ id: 'all-day',
+ title: 'Design review',
+ category: 'Design',
+ start: '2026-05-13',
+ end: '2026-05-13',
+ }),
+ createEventFromISO({
+ id: 'outside',
+ title: 'Outside range',
+ category: 'Blocked',
+ start: '2026-08-13',
+ end: '2026-08-13',
+ }),
+ ];
+
+ it('filters array events to the active view range', async () => {
+ render(
+ <XDSSchedule
+ view={createXDSScheduleMonthlyView()}
+ events={events}
+ categories={categories}
+ date={Date.UTC(2026, 4, 13)}
+ focusDate={Date.UTC(2026, 4, 13)}
+ timezoneID="UTC"
+ />,
+ );
+
+ await waitFor(() => {
+ expect(screen.getByText('Visible sync')).toBeInTheDocument();
+ });
+ expect(screen.getByText('Design review')).toBeInTheDocument();
+ expect(screen.queryByText('Outside range')).not.toBeInTheDocument();
+ });
+
+ it('loads async events with Instant range boundaries', async () => {
+ const loader = vi.fn(
+ async (_start: Instant, _end: Instant) =>
+ [
+ createEventFromISO({
+ id: 'async',
+ title: 'Loaded event',
+ start: '2026-05-13T17:00:00.000Z',
+ end: '2026-05-13T18:00:00.000Z',
+ }),
+ ] as CalendarEvent[],
+ );
+
+ render(
+ <XDSSchedule
+ view={createXDSScheduleDayView()}
+ events={loader}
+ categories={categories}
+ date={Date.UTC(2026, 4, 13)}
+ timezoneID="UTC"
+ />,
+ );
+
+ await waitFor(() => expect(loader).toHaveBeenCalledTimes(1));
+ const [start, end] = loader.mock.calls[0];
+ expect(typeof start).toBe('number');
+ expect(typeof end).toBe('number');
+ expect(start).toBe(Date.UTC(2026, 4, 13));
+ expect(end).toBe(Date.UTC(2026, 4, 14));
+ expect(await screen.findByText('Loaded event')).toBeInTheDocument();
+ });
+
+ it('renders list view grouped by localized day', async () => {
+ const listEvents = [
+ ...events,
+ createEventFromISO({
+ id: 'overnight',
+ title: 'Overnight migration',
+ category: 'Migration',
+ start: '2026-05-13T23:00:00.000Z',
+ end: '2026-05-14T02:00:00.000Z',
+ }),
+ ];
+
+ render(
+ <XDSSchedule
+ view={createXDSScheduleListView({days: 7})}
+ events={listEvents}
+ categories={categories}
+ date={Date.UTC(2026, 4, 13)}
+ timezoneID="UTC"
+ />,
+ );
+
+ await waitFor(() => {
+ expect(screen.getByText('Wed')).toBeInTheDocument();
+ });
+ expect(screen.getByText('13')).toBeInTheDocument();
+ expect(screen.getByText('Visible sync')).toBeInTheDocument();
+ expect(screen.getByText('Design review')).toBeInTheDocument();
+ expect(screen.getAllByText('11:00 PM - 2:00 AM')).toHaveLength(2);
+ });
+
+ it('renders weekly view with the same month title as monthly view', () => {
+ render(
+ <XDSSchedule
+ view={createXDSScheduleWeeklyView()}
+ events={events}
+ categories={categories}
+ date={Date.UTC(2026, 4, 13)}
+ focusDate={Date.UTC(2026, 4, 13)}
+ timezoneID="UTC"
+ />,
+ );
+
+ expect(screen.getByRole('region', {name: 'May 2026'})).toBeInTheDocument();
+ });
+
+ it('exposes monthly view as an ARIA grid', () => {
+ render(
+ <XDSSchedule
+ view={createXDSScheduleMonthlyView()}
+ events={events}
+ categories={categories}
+ date={Date.UTC(2026, 4, 13)}
+ focusDate={Date.UTC(2026, 4, 13)}
+ timezoneID="UTC"
+ />,
+ );
+
+ expect(screen.getByRole('grid', {name: 'May 2026'})).toBeInTheDocument();
+ expect(
+ screen.getByRole('columnheader', {name: 'Wednesday'}),
+ ).toBeInTheDocument();
+ expect(
+ screen.getByRole('columnheader', {name: 'Wednesday'}),
+ ).toHaveAttribute('aria-colindex', '4');
+ expect(
+ screen.getByRole('gridcell', {name: 'Wednesday, May 13, 2026'}),
+ ).toBeInTheDocument();
+ expect(
+ screen.getByRole('gridcell', {name: 'Wednesday, May 13, 2026'}),
+ ).toHaveAttribute('aria-current', 'date');
+ expect(
+ screen.getByText('Visible sync, Sync, 4:00 PM - 4:30 PM'),
+ ).toBeInTheDocument();
+ expect(
+ screen.getByText('Design review, Design, all day'),
+ ).toBeInTheDocument();
+ });
+
+ it('exposes time grid views as ARIA grids', () => {
+ render(
+ <XDSSchedule
+ view={createXDSScheduleDayView({minHour: 8, maxHour: 10})}
+ events={events}
+ categories={categories}
+ date={Date.UTC(2026, 4, 13)}
+ focusDate={Date.UTC(2026, 4, 13)}
+ timezoneID="UTC"
+ />,
+ );
+
+ expect(
+ screen.getByRole('grid', {name: 'Schedule time grid'}),
+ ).toBeInTheDocument();
+ expect(
+ screen.getByRole('columnheader', {name: 'Wednesday, May 13, 2026'}),
+ ).toBeInTheDocument();
+ expect(
+ screen.getByRole('columnheader', {name: 'Wednesday, May 13, 2026'}),
+ ).toHaveAttribute('aria-colindex', '2');
+ expect(
+ screen.getByRole('columnheader', {name: 'Wednesday, May 13, 2026'}),
+ ).toHaveAttribute('aria-current', 'date');
+ expect(
+ screen.getByRole('gridcell', {
+ name: 'Wednesday, May 13, 2026 all day. Design review, Design, all day',
+ }),
+ ).toBeInTheDocument();
+ expect(
+ screen.getByRole('gridcell', {name: 'Wednesday, May 13, 2026 8 AM'}),
+ ).toBeInTheDocument();
+ });
+
+ it('exposes timed events in the accessible time grid cells', () => {
+ render(
+ <XDSSchedule
+ view={createXDSScheduleDayView({minHour: 16, maxHour: 17})}
+ events={events}
+ categories={categories}
+ date={Date.UTC(2026, 4, 13)}
+ timezoneID="UTC"
+ />,
+ );
+
+ expect(
+ screen.getByRole('gridcell', {
+ name: 'Wednesday, May 13, 2026 4 PM. Visible sync, Sync, 4:00 PM - 4:30 PM',
+ }),
+ ).toBeInTheDocument();
+ });
+
+ it('exposes all-day events in the accessible time grid cells', () => {
+ render(
+ <XDSSchedule
+ view={createXDSScheduleDayView({minHour: 8, maxHour: 10})}
+ events={events}
+ categories={categories}
+ date={Date.UTC(2026, 4, 13)}
+ timezoneID="UTC"
+ />,
+ );
+
+ expect(
+ screen.getByRole('gridcell', {
+ name: 'Wednesday, May 13, 2026 all day. Design review, Design, all day',
+ }),
+ ).toBeInTheDocument();
+ });
+
+ it('labels list day headings with the full date', () => {
+ render(
+ <XDSSchedule
+ view={createXDSScheduleListView({days: 7})}
+ events={events}
+ categories={categories}
+ date={Date.UTC(2026, 4, 13)}
+ timezoneID="UTC"
+ />,
+ );
+
+ expect(
+ screen.getByRole('heading', {name: 'Wednesday, May 13, 2026'}),
+ ).toBeInTheDocument();
+ });
+
+ it('calls onChangeDate with the previous view date preserving time of day', () => {
+ const onChangeDate = vi.fn();
+ render(
+ <XDSSchedule
+ view={createXDSScheduleDayView()}
+ events={events}
+ categories={categories}
+ date={Date.UTC(2026, 4, 13, 15, 6) as Instant}
+ onChangeDate={onChangeDate}
+ timezoneID="UTC"
+ />,
+ );
+
+ fireEvent.click(screen.getByRole('button', {name: 'Previous day'}));
+ expect(onChangeDate).toHaveBeenCalledWith(Date.UTC(2026, 4, 12, 15, 6));
+ });
+
+ it('allows plugins to customize header slots', () => {
+ const plugin: XDSSchedulePlugin = {
+ renderHeader: (_startContent, centerContent, endContent) => ({
+ startContent: <span>Custom start</span>,
+ centerContent,
+ endContent,
+ }),
+ };
+
+ render(
+ <XDSSchedule
+ view={createXDSScheduleDayView()}
+ events={events}
+ categories={categories}
+ date={Date.UTC(2026, 4, 13) as Instant}
+ timezoneID="UTC"
+ plugins={[plugin]}
+ />,
+ );
+
+ expect(screen.getByText('Custom start')).toBeInTheDocument();
+ expect(
+ screen.queryByRole('button', {name: 'Previous day'}),
+ ).not.toBeInTheDocument();
+ });
+
+ it('renders a view selector plugin in the header end slot', () => {
+ const onChangeView = vi.fn();
+ const dayView = createXDSScheduleDayView();
+ const monthView = createXDSScheduleMonthlyView();
+ const viewOptions = [
+ {view: monthView, label: 'Month'},
+ {view: dayView, label: 'Day'},
+ ];
+
+ function ScheduleWithViewSelector() {
+ const viewSelectorPlugin = useXDSScheduleViewSelectorPlugin(viewOptions, {
+ onChangeView,
+ });
+ return (
+ <XDSSchedule
+ view={dayView}
+ events={events}
+ categories={categories}
+ date={Date.UTC(2026, 4, 13) as Instant}
+ timezoneID="UTC"
+ plugins={[viewSelectorPlugin]}
+ />
+ );
+ }
+
+ render(<ScheduleWithViewSelector />);
+
+ expect(screen.getByRole('button', {name: /Day/})).toBeInTheDocument();
+ });
+});
+
+describe('sortEvents', () => {
+ it('sorts mixed all-day and instant events by start time', () => {
+ const sortedEvents = sortEvents(
+ [
+ createEventFromISO({
+ id: 'instant-later',
+ title: 'A later timed event',
+ start: '2026-05-14T16:00:00.000Z',
+ end: '2026-05-14T17:00:00.000Z',
+ }),
+ createEventFromISO({
+ id: 'all-day-earlier',
+ title: 'Z earlier all-day event',
+ start: '2026-05-13',
+ end: '2026-05-13',
+ }),
+ createEventFromISO({
+ id: 'instant-earliest',
+ title: 'Middle timed event',
+ start: '2026-05-12T16:00:00.000Z',
+ end: '2026-05-12T17:00:00.000Z',
+ }),
+ ],
+ 'UTC',
+ );
+
+ expect(sortedEvents.map(event => event.id)).toEqual([
+ 'instant-earliest',
+ 'all-day-earlier',
+ 'instant-later',
+ ]);
+ });
+});
diff --git a/packages/lab/src/Schedule/XDSSchedule.tsx b/packages/lab/src/Schedule/XDSSchedule.tsx
new file mode 100644
index 0000000000..dca4043758
--- /dev/null
+++ b/packages/lab/src/Schedule/XDSSchedule.tsx
@@ -0,0 +1,306 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file XDSSchedule.tsx
+ * @input Calendar events, event loader functions, view objects, date/focusDate/timezone props
+ * @output Generic read-only schedule shell that renders arbitrary schedule views
+ * @position Lab component shell; concrete views live in separate view files
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/lab/src/Schedule/index.ts
+ * - /packages/lab/src/Schedule/XDSSchedule.test.tsx
+ * - /apps/storybook/stories/Schedule.stories.tsx
+ */
+
+import {Suspense, useCallback, useMemo, useState} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import type {XDSBaseProps} from '@xds/core';
+import {xdsClassName, mergeProps, plainDateFromInstant} from '@xds/core/utils';
+import {eventOverlapsRange, getBrowserTimezoneID, sortEvents} from './dateMath';
+import {XDSScheduleContext} from './context';
+import {defaultXDSSchedulePlugins} from './plugins';
+import {styles} from './shared';
+import {createZonedDateTime} from './zonedDateTime';
+import type {
+ CalendarEvent,
+ Instant,
+ ScheduleRange,
+ XDSScheduleCategory,
+ XDSScheduleEventSource,
+ XDSSchedulePlugin,
+ XDSScheduleView,
+ XDSScheduleViewOptions,
+ ZonedDateTime,
+ ZonedDateTimeRange,
+} from './types';
+
+export interface XDSScheduleProps<
+ Options extends XDSScheduleViewOptions = XDSScheduleViewOptions,
+> extends XDSBaseProps<HTMLDivElement> {
+ /** View object returned by a `createXDSSchedule*View()` factory. */
+ view: XDSScheduleView<Options>;
+ /** Static calendar events or an async loader called with the active Instant range. */
+ events: XDSScheduleEventSource;
+ /** Category definitions used to style and label events by their `category` value. */
+ categories?: ReadonlyArray<XDSScheduleCategory>;
+ /** Focused Instant used to choose the currently rendered range. */
+ date: Instant;
+ /** Instant highlighted as the user's focus/current date. Defaults to mount time. */
+ focusDate?: Instant;
+ /** Called by pagination plugins when the rendered range should change. */
+ onChangeDate?: (date: Instant) => void;
+ /** IANA timezone ID used for date math and localized rendering. Defaults to browser timezone. */
+ timezoneID?: string;
+ /** Header/rendering plugins. Defaults to pagination controls. */
+ plugins?: ReadonlyArray<XDSSchedulePlugin>;
+}
+
+interface EventRecord {
+ status: 'pending' | 'fulfilled' | 'rejected';
+ promise: Promise<void>;
+ value: ReadonlyArray<CalendarEvent>;
+ error: unknown;
+}
+
+const eventLoaderCache = new WeakMap<
+ Exclude<XDSScheduleEventSource, ReadonlyArray<CalendarEvent>>,
+ Map<string, EventRecord>
+>();
+
+function readAsyncEvents(
+ loader: Exclude<XDSScheduleEventSource, ReadonlyArray<CalendarEvent>>,
+ start: Instant,
+ end: Instant,
+): ReadonlyArray<CalendarEvent> {
+ let loaderCache = eventLoaderCache.get(loader);
+ if (loaderCache == null) {
+ loaderCache = new Map();
+ eventLoaderCache.set(loader, loaderCache);
+ }
+
+ const key = `${start}:${end}`;
+ let record = loaderCache.get(key);
+ if (record == null) {
+ record = {
+ status: 'pending',
+ promise: Promise.resolve()
+ .then(() => loader(start, end))
+ .then(
+ value => {
+ if (record != null) {
+ record.status = 'fulfilled';
+ record.value = value;
+ }
+ },
+ error => {
+ if (record != null) {
+ record.status = 'rejected';
+ record.error = error;
+ }
+ },
+ ),
+ value: [],
+ error: null,
+ };
+ loaderCache.set(key, record);
+ }
+
+ if (record.status === 'pending') {
+ throw record.promise;
+ }
+ if (record.status === 'rejected') {
+ throw record.error;
+ }
+ return record.value;
+}
+
+function resolveEvents(
+ eventSource: XDSScheduleEventSource,
+ range: ScheduleRange,
+ timezoneID: string,
+): ReadonlyArray<CalendarEvent> {
+ const events =
+ typeof eventSource === 'function'
+ ? readAsyncEvents(eventSource, range.start, range.end)
+ : eventSource;
+ return sortEvents(
+ events.filter(event => eventOverlapsRange(event, range, timezoneID)),
+ timezoneID,
+ );
+}
+
+function getRange<Options extends XDSScheduleViewOptions>(
+ view: XDSScheduleView<Options>,
+ date: ZonedDateTime,
+): ScheduleRange {
+ const [start, end] = view.getDateRange(date);
+ return {
+ start: start.instant,
+ end: end.instant,
+ startDate: plainDateFromInstant(start.instant, start.timezoneID),
+ endDate: plainDateFromInstant(end.instant, end.timezoneID),
+ };
+}
+
+function ScheduleViewContent<Options extends XDSScheduleViewOptions>({
+ view,
+ eventSource,
+ categories,
+ date,
+ focusDate,
+ isLoading,
+ onPreviousDate,
+ previousDateLabel,
+ onToday,
+ onNextDate,
+ nextDateLabel,
+ plugins,
+}: {
+ view: XDSScheduleView<Options>;
+ eventSource: XDSScheduleEventSource;
+ categories: ReadonlyArray<XDSScheduleCategory>;
+ date: ZonedDateTime;
+ focusDate: ZonedDateTime;
+ isLoading: boolean;
+ onPreviousDate: () => void;
+ previousDateLabel: string;
+ onToday: () => void;
+ onNextDate: () => void;
+ nextDateLabel: string;
+ plugins: ReadonlyArray<XDSSchedulePlugin>;
+}) {
+ const Component = view.component;
+ const range = getRange(view, date);
+ const events = isLoading
+ ? []
+ : resolveEvents(eventSource, range, date.timezoneID);
+
+ return (
+ <XDSScheduleContext.Provider
+ value={{
+ events,
+ categories,
+ date,
+ focusDate,
+ timezoneID: date.timezoneID,
+ range,
+ isLoading,
+ onPreviousDate,
+ previousDateLabel,
+ onToday,
+ onNextDate,
+ nextDateLabel,
+ view,
+ plugins,
+ }}>
+ <Component options={view.options} />
+ </XDSScheduleContext.Provider>
+ );
+}
+
+export function XDSSchedule({
+ view,
+ events,
+ categories = [],
+ date,
+ focusDate: focusDateProp,
+ onChangeDate,
+ timezoneID: timezoneIDProp,
+ plugins = defaultXDSSchedulePlugins,
+ xstyle,
+ className,
+ style,
+ ...rest
+}: XDSScheduleProps) {
+ const timezoneID = timezoneIDProp ?? getBrowserTimezoneID();
+ const [internalFocusDate] = useState<Instant>(() => Date.now() as Instant);
+ const focusDate = focusDateProp ?? internalFocusDate;
+ const zonedDateTime = useMemo(
+ () => createZonedDateTime(date, timezoneID),
+ [date, timezoneID],
+ );
+ const focusZonedDateTime = useMemo(
+ () => createZonedDateTime(focusDate, timezoneID),
+ [focusDate, timezoneID],
+ );
+ const updateDate = useCallback(
+ (nextDate: Instant) => {
+ onChangeDate?.(nextDate);
+ },
+ [onChangeDate],
+ );
+ const shiftToRange = useCallback(
+ (nextRange: ZonedDateTimeRange) => {
+ const currentRange = view.getDateRange(zonedDateTime);
+ updateDate(
+ (zonedDateTime.instant +
+ nextRange[0].instant -
+ currentRange[0].instant) as Instant,
+ );
+ },
+ [updateDate, view, zonedDateTime],
+ );
+ const previousDateRange = useMemo(
+ () => view.getPreviousDateRange(zonedDateTime),
+ [view, zonedDateTime],
+ );
+ const nextDateRange = useMemo(
+ () => view.getNextDateRange(zonedDateTime),
+ [view, zonedDateTime],
+ );
+ const onPreviousDate = useCallback(() => {
+ shiftToRange(previousDateRange.range);
+ }, [previousDateRange, shiftToRange]);
+ const onToday = useCallback(() => {
+ updateDate(Date.now() as Instant);
+ }, [updateDate]);
+ const onNextDate = useCallback(() => {
+ shiftToRange(nextDateRange.range);
+ }, [nextDateRange, shiftToRange]);
+
+ return (
+ <div
+ {...rest}
+ {...mergeProps(
+ xdsClassName('schedule'),
+ stylex.props(styles.root, xstyle),
+ className,
+ style,
+ )}>
+ <Suspense
+ fallback={
+ <ScheduleViewContent
+ view={view}
+ eventSource={[]}
+ categories={categories}
+ date={zonedDateTime}
+ focusDate={focusZonedDateTime}
+ isLoading
+ onPreviousDate={onPreviousDate}
+ previousDateLabel={previousDateRange.label}
+ onToday={onToday}
+ onNextDate={onNextDate}
+ nextDateLabel={nextDateRange.label}
+ plugins={plugins}
+ />
+ }>
+ <ScheduleViewContent
+ view={view}
+ eventSource={events}
+ categories={categories}
+ date={zonedDateTime}
+ focusDate={focusZonedDateTime}
+ isLoading={false}
+ onPreviousDate={onPreviousDate}
+ previousDateLabel={previousDateRange.label}
+ onToday={onToday}
+ onNextDate={onNextDate}
+ nextDateLabel={nextDateRange.label}
+ plugins={plugins}
+ />
+ </Suspense>
+ </div>
+ );
+}
diff --git a/packages/lab/src/Schedule/context.tsx b/packages/lab/src/Schedule/context.tsx
new file mode 100644
index 0000000000..92320407e9
--- /dev/null
+++ b/packages/lab/src/Schedule/context.tsx
@@ -0,0 +1,49 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file context.tsx
+ * @input Resolved XDSSchedule events, range, timezone, and active date
+ * @output Schedule context object and hook used by view components
+ * @position Internal context bridge between generic XDSSchedule and concrete views
+ */
+
+import {createContext, useContext} from 'react';
+import type {
+ CalendarEvent,
+ ScheduleRange,
+ ZonedDateTime,
+ XDSScheduleCategory,
+ XDSSchedulePlugin,
+ XDSScheduleViewBase,
+} from './types';
+
+export interface XDSScheduleContextValue {
+ events: ReadonlyArray<CalendarEvent>;
+ categories: ReadonlyArray<XDSScheduleCategory>;
+ date: ZonedDateTime;
+ focusDate: ZonedDateTime;
+ timezoneID: string;
+ range: ScheduleRange;
+ isLoading: boolean;
+ onPreviousDate: () => void;
+ previousDateLabel: string;
+ onToday: () => void;
+ onNextDate: () => void;
+ nextDateLabel: string;
+ view: XDSScheduleViewBase;
+ plugins: ReadonlyArray<XDSSchedulePlugin>;
+}
+
+export const XDSScheduleContext = createContext<XDSScheduleContextValue | null>(
+ null,
+);
+
+export function useXDSScheduleContext(): XDSScheduleContextValue {
+ const context = useContext(XDSScheduleContext);
+ if (context == null) {
+ throw new Error('XDSSchedule views must be rendered inside XDSSchedule.');
+ }
+ return context;
+}
diff --git a/packages/lab/src/Schedule/dateMath.ts b/packages/lab/src/Schedule/dateMath.ts
new file mode 100644
index 0000000000..a9ef1a3f90
--- /dev/null
+++ b/packages/lab/src/Schedule/dateMath.ts
@@ -0,0 +1,115 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file dateMath.ts
+ * @input PlainDate records, Instant epoch milliseconds, IANA timezone IDs
+ * @output Pure range, conversion, formatting, and event-overlap utilities
+ * @position Shared schedule utility layer; consumed by XDSSchedule and tests
+ */
+
+import {
+ type PlainDate,
+ plainDateAddDays,
+ plainDateFromInstant,
+ plainDateIsAfter,
+ plainDateIsBefore,
+ plainDateToInstant,
+} from '@xds/core/utils';
+import type {CalendarDayEvent, CalendarEvent} from './CalendarEvent';
+import type {Instant, ScheduleRange} from './types';
+
+export function getBrowserTimezoneID(): string {
+ return Intl.DateTimeFormat().resolvedOptions().timeZone || 'UTC';
+}
+
+export function isDayEvent(event: CalendarEvent): event is CalendarDayEvent {
+ return typeof event.start !== 'number';
+}
+
+export function getScheduleRangeFromDates({
+ startDate,
+ endDate,
+ timezoneID,
+}: {
+ startDate: PlainDate;
+ endDate: PlainDate;
+ timezoneID: string;
+}): ScheduleRange {
+ return {
+ startDate,
+ endDate,
+ start: plainDateToInstant(startDate, timezoneID) as Instant,
+ end: plainDateToInstant(endDate, timezoneID) as Instant,
+ };
+}
+
+export function enumerateDates(start: PlainDate, endExclusive: PlainDate) {
+ const dates: PlainDate[] = [];
+ let current = start;
+ while (plainDateIsBefore(current, endExclusive)) {
+ dates.push(current);
+ current = plainDateAddDays(current, 1);
+ }
+ return dates;
+}
+
+export function eventOverlapsRange(
+ event: CalendarEvent,
+ range: ScheduleRange,
+ timezoneID: string,
+): boolean {
+ if (isDayEvent(event)) {
+ const eventStart = plainDateToInstant(event.start, timezoneID) as Instant;
+ const eventEnd = plainDateToInstant(
+ plainDateAddDays(event.end, 1),
+ timezoneID,
+ ) as Instant;
+ return eventStart < range.end && eventEnd > range.start;
+ }
+ return event.start < range.end && event.end > range.start;
+}
+
+export function eventOccursOnDate(
+ event: CalendarEvent,
+ date: PlainDate,
+ timezoneID: string,
+): boolean {
+ if (isDayEvent(event)) {
+ return (
+ !plainDateIsAfter(event.start, date) &&
+ !plainDateIsBefore(event.end, date)
+ );
+ }
+ const startDate = plainDateFromInstant(event.start, timezoneID);
+ const endDate = plainDateFromInstant(
+ Math.max(event.end - 1, event.start),
+ timezoneID,
+ );
+ return (
+ !plainDateIsAfter(startDate, date) && !plainDateIsBefore(endDate, date)
+ );
+}
+
+export function sortEvents(
+ events: ReadonlyArray<CalendarEvent>,
+ timezoneID: string,
+): CalendarEvent[] {
+ return [...events].sort((a, b) => {
+ const aStart = getEventSortStart(a, timezoneID);
+ const bStart = getEventSortStart(b, timezoneID);
+ return aStart < bStart
+ ? -1
+ : aStart > bStart
+ ? 1
+ : a.title.localeCompare(b.title);
+ });
+}
+
+function getEventSortStart(
+ event: CalendarEvent,
+ timezoneID: string,
+): Instant {
+ return isDayEvent(event)
+ ? (plainDateToInstant(event.start, timezoneID) as Instant)
+ : event.start;
+}
diff --git a/packages/lab/src/Schedule/index.ts b/packages/lab/src/Schedule/index.ts
new file mode 100644
index 0000000000..832cb6f12d
--- /dev/null
+++ b/packages/lab/src/Schedule/index.ts
@@ -0,0 +1,61 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file index.ts
+ * @input XDSSchedule implementation and public schedule types
+ * @output Public exports for @xds/lab Schedule
+ * @position Component entry point; re-exported by packages/lab/src/index.ts
+ */
+
+export {XDSSchedule, type XDSScheduleProps} from './XDSSchedule';
+export {createEventFromISO} from './CalendarEvent';
+export {
+ createXDSScheduleMonthlyView,
+ type XDSScheduleMonthlyViewOptions,
+} from './MonthlyView';
+export {
+ createXDSScheduleWeeklyView,
+ type XDSScheduleWeeklyViewOptions,
+} from './WeeklyView';
+export {
+ createXDSScheduleDayView,
+ type XDSScheduleDayViewOptions,
+} from './DayView';
+export {
+ createXDSScheduleListView,
+ type XDSScheduleListViewOptions,
+} from './ListView';
+export {XDSScheduleContext, useXDSScheduleContext} from './context';
+export {
+ defaultXDSSchedulePlugins,
+ useXDSSchedulePaginationPlugin,
+ useXDSScheduleViewSelectorPlugin,
+} from './plugins';
+export type {XDSScheduleContextValue} from './context';
+export type {XDSSchedulePaginationPluginOptions} from './plugins/PaginationPlugin';
+export type {
+ XDSScheduleViewSelectorOption,
+ XDSScheduleViewSelectorPluginOptions,
+} from './plugins/ViewSelectorPlugin';
+
+export type {
+ CalendarDayEvent,
+ CalendarEvent,
+ CalendarEventBase,
+ CalendarInstantEvent,
+ Instant,
+ PlainDate,
+ ScheduleRange,
+ ZonedDateTime,
+ ZonedDateTimeRange,
+ XDSScheduleCategory,
+ XDSScheduleDate,
+ XDSScheduleEventColor,
+ XDSScheduleEventSource,
+ XDSScheduleHeaderContent,
+ XDSSchedulePlugin,
+ XDSSchedulePluginPosition,
+ XDSScheduleView,
+ XDSScheduleViewBase,
+ XDSScheduleViewOptions,
+} from './types';
diff --git a/packages/lab/src/Schedule/plugins/PaginationPlugin.tsx b/packages/lab/src/Schedule/plugins/PaginationPlugin.tsx
new file mode 100644
index 0000000000..177f97e59d
--- /dev/null
+++ b/packages/lab/src/Schedule/plugins/PaginationPlugin.tsx
@@ -0,0 +1,98 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file PaginationPlugin.tsx
+ * @input Schedule date navigation callbacks from XDSSchedule context
+ * @output Hook and default plugin that render previous, today, and next controls
+ * @position Built-in XDSSchedule plugin; re-exported from plugins.tsx
+ */
+
+import {useMemo, type ReactNode} from 'react';
+import {XDSButton} from '@xds/core/Button';
+import {XDSButtonGroup} from '@xds/core/ButtonGroup';
+import {XDSIcon} from '@xds/core/Icon';
+import {XDSIconButton} from '@xds/core/IconButton';
+import {useXDSScheduleContext} from '../context';
+import type {
+ XDSScheduleHeaderContent,
+ XDSSchedulePlugin,
+ XDSSchedulePluginPosition,
+} from '../types';
+
+export interface XDSSchedulePaginationPluginOptions {
+ position?: XDSSchedulePluginPosition;
+}
+
+function XDSSchedulePaginationControls() {
+ const {
+ onPreviousDate,
+ previousDateLabel,
+ onToday,
+ onNextDate,
+ nextDateLabel,
+ } = useXDSScheduleContext();
+ return (
+ <XDSButtonGroup label="Schedule pagination" size="sm">
+ <XDSIconButton
+ label={previousDateLabel}
+ icon={<XDSIcon icon="chevronLeft" size="sm" color="inherit" />}
+ onClick={onPreviousDate}
+ />
+ <XDSButton label="Today" size="sm" onClick={onToday} />
+ <XDSIconButton
+ label={nextDateLabel}
+ icon={<XDSIcon icon="chevronRight" size="sm" color="inherit" />}
+ onClick={onNextDate}
+ />
+ </XDSButtonGroup>
+ );
+}
+
+function createXDSSchedulePaginationPlugin({
+ position = 'start',
+}: XDSSchedulePaginationPluginOptions = {}): XDSSchedulePlugin {
+ return {
+ renderHeader(
+ startContent: ReactNode,
+ centerContent: ReactNode,
+ endContent: ReactNode,
+ ): XDSScheduleHeaderContent {
+ const controls = <XDSSchedulePaginationControls />;
+ return position === 'start'
+ ? {
+ startContent: (
+ <>
+ {controls}
+ {startContent}
+ </>
+ ),
+ centerContent,
+ endContent,
+ }
+ : {
+ startContent,
+ centerContent,
+ endContent: (
+ <>
+ {endContent}
+ {controls}
+ </>
+ ),
+ };
+ },
+ };
+}
+
+export const defaultXDSSchedulePaginationPlugin =
+ createXDSSchedulePaginationPlugin();
+
+export function useXDSSchedulePaginationPlugin({
+ position = 'start',
+}: XDSSchedulePaginationPluginOptions = {}): XDSSchedulePlugin {
+ return useMemo(
+ () => createXDSSchedulePaginationPlugin({position}),
+ [position],
+ );
+}
diff --git a/packages/lab/src/Schedule/plugins/ViewSelectorPlugin.tsx b/packages/lab/src/Schedule/plugins/ViewSelectorPlugin.tsx
new file mode 100644
index 0000000000..0f2f2e4caf
--- /dev/null
+++ b/packages/lab/src/Schedule/plugins/ViewSelectorPlugin.tsx
@@ -0,0 +1,126 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file ViewSelectorPlugin.tsx
+ * @input Schedule view options and caller-provided view change callback
+ * @output Hook that renders an XDSDropdownMenu plugin for caller-provided views
+ * @position Built-in XDSSchedule plugin; re-exported from plugins.tsx
+ */
+
+import {useMemo, type ReactNode} from 'react';
+import {XDSDropdownMenu, XDSDropdownMenuItem} from '@xds/core/DropdownMenu';
+import {XDSIcon} from '@xds/core/Icon';
+import {useXDSScheduleContext} from '../context';
+import type {
+ XDSScheduleHeaderContent,
+ XDSSchedulePlugin,
+ XDSSchedulePluginPosition,
+ XDSScheduleView,
+ XDSScheduleViewBase,
+} from '../types';
+
+export interface XDSScheduleViewSelectorOption<
+ View extends XDSScheduleViewBase = XDSScheduleView,
+> {
+ view: View;
+ label: string;
+}
+
+export interface XDSScheduleViewSelectorPluginOptions<
+ View extends XDSScheduleViewBase = XDSScheduleView,
+> {
+ onChangeView?: (view: View) => void;
+ position?: XDSSchedulePluginPosition;
+}
+
+function XDSScheduleViewSelectorControl<View extends XDSScheduleViewBase>({
+ onChangeView,
+ options,
+}: {
+ onChangeView?: (view: View) => void;
+ options: ReadonlyArray<XDSScheduleViewSelectorOption<View>>;
+}) {
+ const {view} = useXDSScheduleContext();
+ const selectedIndex = options.findIndex(option => option.view === view);
+ const selectedLabel = options[selectedIndex]?.label ?? 'View';
+ return (
+ <XDSDropdownMenu
+ button={{
+ label: selectedLabel,
+ size: 'sm',
+ isDisabled: onChangeView == null,
+ }}
+ menuWidth={160}>
+ {options.map((option, index) => (
+ <XDSDropdownMenuItem
+ key={option.label}
+ label={option.label}
+ onClick={() => onChangeView?.(option.view)}>
+ {index === selectedIndex ? (
+ <XDSIcon icon="check" size="sm" color="primary" />
+ ) : null}
+ </XDSDropdownMenuItem>
+ ))}
+ </XDSDropdownMenu>
+ );
+}
+
+function createXDSScheduleViewSelectorPlugin<View extends XDSScheduleViewBase>(
+ options: ReadonlyArray<XDSScheduleViewSelectorOption<View>>,
+ {
+ onChangeView,
+ position = 'end',
+ }: XDSScheduleViewSelectorPluginOptions<View> = {},
+): XDSSchedulePlugin {
+ return {
+ renderHeader(
+ startContent: ReactNode,
+ centerContent: ReactNode,
+ endContent: ReactNode,
+ ): XDSScheduleHeaderContent {
+ const control = (
+ <XDSScheduleViewSelectorControl
+ onChangeView={onChangeView}
+ options={options}
+ />
+ );
+ return position === 'start'
+ ? {
+ startContent: (
+ <>
+ {startContent}
+ {control}
+ </>
+ ),
+ centerContent,
+ endContent,
+ }
+ : {
+ startContent,
+ centerContent,
+ endContent: (
+ <>
+ {endContent}
+ {control}
+ </>
+ ),
+ };
+ },
+ };
+}
+
+export function useXDSScheduleViewSelectorPlugin<
+ View extends XDSScheduleViewBase,
+>(
+ options: ReadonlyArray<XDSScheduleViewSelectorOption<View>>,
+ pluginOptions: XDSScheduleViewSelectorPluginOptions<View> = {},
+): XDSSchedulePlugin {
+ const {onChangeView, position = 'end'} = pluginOptions;
+ return useMemo(
+ () =>
+ createXDSScheduleViewSelectorPlugin(options, {onChangeView, position}),
+ [onChangeView, options, position],
+ );
+}
diff --git a/packages/lab/src/Schedule/plugins/index.tsx b/packages/lab/src/Schedule/plugins/index.tsx
new file mode 100644
index 0000000000..b7a30b2b06
--- /dev/null
+++ b/packages/lab/src/Schedule/plugins/index.tsx
@@ -0,0 +1,20 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file plugins.tsx
+ * @input Built-in schedule plugin hooks and stable defaults
+ * @output Default XDSSchedule plugin list and plugin hook re-exports
+ * @position Plugin barrel; plugin implementations live in separate files
+ */
+
+import {defaultXDSSchedulePaginationPlugin} from './PaginationPlugin';
+import type {XDSSchedulePlugin} from '../types';
+
+export {useXDSSchedulePaginationPlugin} from './PaginationPlugin';
+export {useXDSScheduleViewSelectorPlugin} from './ViewSelectorPlugin';
+
+export const defaultXDSSchedulePlugins: ReadonlyArray<XDSSchedulePlugin> = [
+ defaultXDSSchedulePaginationPlugin,
+];
diff --git a/packages/lab/src/Schedule/shared.tsx b/packages/lab/src/Schedule/shared.tsx
new file mode 100644
index 0000000000..b41d419640
--- /dev/null
+++ b/packages/lab/src/Schedule/shared.tsx
@@ -0,0 +1,1304 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file shared.tsx
+ * @input Schedule events, dates, timezone IDs, and display metadata
+ * @output Shared rendering primitives, formatters, and styles for schedule views
+ * @position Internal view utility module; consumed by Monthly, Weekly, Day, and List views
+ */
+
+import {type ReactNode} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import {
+ borderVars,
+ colorVars,
+ fontWeightVars,
+ radiusVars,
+ spacingVars,
+ typographyVars,
+ typeScaleVars,
+} from '@xds/core/theme/tokens.stylex';
+import {XDSSpinner} from '@xds/core/Spinner';
+import {XDSHStack} from '@xds/core/Stack';
+import {XDSHeading, XDSText} from '@xds/core/Text';
+import {
+ plainDateFromInstant,
+ plainDateIsAfter,
+ plainDateIsBefore,
+ plainDateToInstant,
+ type PlainDate,
+} from '@xds/core/utils';
+import {isDayEvent} from './dateMath';
+import {useXDSScheduleContext} from './context';
+import type {
+ CalendarEvent,
+ CalendarInstantEvent,
+ Instant,
+ XDSScheduleCategory,
+ XDSScheduleHeaderContent,
+ XDSScheduleEventColor,
+} from './types';
+
+const DEFAULT_EVENT_CATEGORY: XDSScheduleCategory = {
+ label: 'Event',
+ color: 'blue',
+};
+
+export function ScheduleFrame({
+ title,
+ titleLabel,
+ isLoading,
+ children,
+}: {
+ title: ReactNode;
+ titleLabel: string;
+ isLoading: boolean;
+ children: ReactNode;
+}) {
+ const {plugins} = useXDSScheduleContext();
+ const initialHeader: XDSScheduleHeaderContent = {
+ startContent: null,
+ centerContent: (
+ <span {...stylex.props(styles.headerTitleContent)}>
+ <XDSHeading level={2}>{title}</XDSHeading>
+ <span
+ {...stylex.props(
+ styles.loadingSpinner,
+ !isLoading && styles.loadingSpinnerHidden,
+ )}>
+ <XDSSpinner size="md" aria-label="Loading events" />
+ </span>
+ </span>
+ ),
+ endContent: null,
+ };
+ const header = plugins.reduce(
+ (content, plugin) =>
+ plugin.renderHeader?.(
+ content.startContent,
+ content.centerContent,
+ content.endContent,
+ ) ?? content,
+ initialHeader,
+ );
+
+ return (
+ <section {...stylex.props(styles.frame)} aria-label={titleLabel}>
+ <div {...stylex.props(styles.header)}>
+ <XDSHStack gap={8} align="center" xstyle={styles.headerControls}>
+ {header.startContent}
+ </XDSHStack>
+ <XDSHStack gap={8} align="center" xstyle={styles.headerTitle}>
+ {header.centerContent}
+ </XDSHStack>
+ <XDSHStack
+ gap={8}
+ align="center"
+ justify="end"
+ xstyle={styles.headerStatus}>
+ {header.endContent}
+ </XDSHStack>
+ </div>
+ {children}
+ </section>
+ );
+}
+
+export function ScheduleMonthTitle({
+ date,
+ timezoneID,
+}: {
+ date: PlainDate;
+ timezoneID: string;
+}) {
+ const month = new Intl.DateTimeFormat(undefined, {
+ month: 'long',
+ timeZone: timezoneID,
+ }).format(new Date(Date.UTC(date.year, date.month - 1, date.day, 12)));
+ return (
+ <>
+ <span {...stylex.props(styles.titleEmphasis)}>{month}</span> {date.year}
+ </>
+ );
+}
+
+export function ScheduleRangeMonthTitle({
+ start,
+ end,
+ timezoneID,
+}: {
+ start: PlainDate;
+ end: PlainDate;
+ timezoneID: string;
+}) {
+ if (start.year === end.year && start.month === end.month) {
+ return <ScheduleMonthTitle date={start} timezoneID={timezoneID} />;
+ }
+
+ const startMonth = formatWithPlainDate(start, timezoneID, {month: 'long'});
+ const endMonth = formatWithPlainDate(end, timezoneID, {month: 'long'});
+ return start.year === end.year ? (
+ <>
+ <span {...stylex.props(styles.titleEmphasis)}>{startMonth}</span> -{' '}
+ <span {...stylex.props(styles.titleEmphasis)}>{endMonth}</span> {end.year}
+ </>
+ ) : (
+ <>
+ <span {...stylex.props(styles.titleEmphasis)}>{startMonth}</span>{' '}
+ {start.year} -{' '}
+ <span {...stylex.props(styles.titleEmphasis)}>{endMonth}</span> {end.year}
+ </>
+ );
+}
+
+export function EventPill({
+ event,
+ day,
+ timezoneID,
+ isPast = false,
+}: {
+ event: CalendarEvent;
+ day?: PlainDate;
+ timezoneID?: string;
+ isPast?: boolean;
+}) {
+ const {categories} = useXDSScheduleContext();
+ const category = getEventCategory(event, categories);
+ const timeLabel =
+ day != null && timezoneID != null && !isDayEvent(event)
+ ? formatEventTime(event, day, timezoneID)
+ : null;
+ return (
+ <span
+ {...stylex.props(
+ styles.eventPill,
+ isPast
+ ? eventPastSurfaceColorStyle(category.color)
+ : eventSurfaceColorStyle(category.color),
+ )}>
+ {timeLabel != null && (
+ <XDSText type="supporting" color="inherit" xstyle={styles.eventTime}>
+ {timeLabel}
+ </XDSText>
+ )}
+ <XDSText
+ type="supporting"
+ color="inherit"
+ weight="bold"
+ xstyle={styles.eventTitle}>
+ {event.title}
+ </XDSText>
+ </span>
+ );
+}
+
+export function MonthEventPill({
+ event,
+ timezoneID,
+ isPast = false,
+}: {
+ event: CalendarEvent;
+ timezoneID: string;
+ isPast?: boolean;
+}) {
+ const {categories} = useXDSScheduleContext();
+ const category = getEventCategory(event, categories);
+ const timeLabel = isDayEvent(event)
+ ? null
+ : formatEventStartTime(event, timezoneID);
+ return (
+ <span
+ {...stylex.props(
+ styles.eventPill,
+ isPast
+ ? eventPastSurfaceColorStyle(category.color)
+ : eventSurfaceColorStyle(category.color),
+ )}>
+ {timeLabel != null && (
+ <XDSText type="supporting" color="inherit" xstyle={styles.eventTime}>
+ {timeLabel}
+ </XDSText>
+ )}
+ <XDSText
+ type="supporting"
+ color="inherit"
+ weight="bold"
+ xstyle={styles.eventTitle}>
+ {event.title}
+ </XDSText>
+ </span>
+ );
+}
+
+export function ListEventRow({
+ event,
+ timezoneID,
+ isPast = false,
+}: {
+ event: CalendarEvent;
+ timezoneID: string;
+ isPast?: boolean;
+}) {
+ const {categories} = useXDSScheduleContext();
+ const category = getEventCategory(event, categories);
+ return (
+ <div {...stylex.props(styles.listEventRow, isPast && styles.listEventPast)}>
+ <span
+ aria-hidden
+ {...stylex.props(
+ styles.listEventDot,
+ eventDotColorStyle(category.color),
+ )}
+ />
+ <span {...stylex.props(styles.listEventTime)}>
+ {isDayEvent(event)
+ ? 'All day'
+ : formatEventTimeRange(event, timezoneID)}
+ </span>
+ <span {...stylex.props(styles.listEventTitle)}>{event.title}</span>
+ </div>
+ );
+}
+
+export function getEventCategory(
+ event: CalendarEvent,
+ categories: ReadonlyArray<XDSScheduleCategory>,
+): XDSScheduleCategory {
+ return (
+ categories.find(category => category.label === event.category) ??
+ (event.category != null
+ ? {label: event.category, color: DEFAULT_EVENT_CATEGORY.color}
+ : DEFAULT_EVENT_CATEGORY)
+ );
+}
+
+export function eventColorStyle(color: XDSScheduleEventColor | undefined) {
+ switch (color) {
+ case 'cyan':
+ return styles.eventCyan;
+ case 'gray':
+ return styles.eventGray;
+ case 'green':
+ return styles.eventGreen;
+ case 'orange':
+ return styles.eventOrange;
+ case 'pink':
+ return styles.eventPink;
+ case 'purple':
+ return styles.eventPurple;
+ case 'red':
+ return styles.eventRed;
+ case 'teal':
+ return styles.eventTeal;
+ case 'yellow':
+ return styles.eventYellow;
+ case 'blue':
+ default:
+ return styles.eventBlue;
+ }
+}
+
+export function eventDotColorStyle(color: XDSScheduleEventColor | undefined) {
+ switch (color) {
+ case 'cyan':
+ return styles.eventDotCyan;
+ case 'gray':
+ return styles.eventDotGray;
+ case 'green':
+ return styles.eventDotGreen;
+ case 'orange':
+ return styles.eventDotOrange;
+ case 'pink':
+ return styles.eventDotPink;
+ case 'purple':
+ return styles.eventDotPurple;
+ case 'red':
+ return styles.eventDotRed;
+ case 'teal':
+ return styles.eventDotTeal;
+ case 'yellow':
+ return styles.eventDotYellow;
+ case 'blue':
+ default:
+ return styles.eventDotBlue;
+ }
+}
+
+export function eventSurfaceColorStyle(
+ color: XDSScheduleEventColor | undefined,
+) {
+ switch (color) {
+ case 'cyan':
+ return styles.eventSurfaceCyan;
+ case 'gray':
+ return styles.eventSurfaceGray;
+ case 'green':
+ return styles.eventSurfaceGreen;
+ case 'orange':
+ return styles.eventSurfaceOrange;
+ case 'pink':
+ return styles.eventSurfacePink;
+ case 'purple':
+ return styles.eventSurfacePurple;
+ case 'red':
+ return styles.eventSurfaceRed;
+ case 'teal':
+ return styles.eventSurfaceTeal;
+ case 'yellow':
+ return styles.eventSurfaceYellow;
+ case 'blue':
+ default:
+ return styles.eventSurfaceBlue;
+ }
+}
+
+export function eventPastSurfaceColorStyle(
+ color: XDSScheduleEventColor | undefined,
+) {
+ switch (color) {
+ case 'cyan':
+ return styles.eventPastSurfaceCyan;
+ case 'gray':
+ return styles.eventPastSurfaceGray;
+ case 'green':
+ return styles.eventPastSurfaceGreen;
+ case 'orange':
+ return styles.eventPastSurfaceOrange;
+ case 'pink':
+ return styles.eventPastSurfacePink;
+ case 'purple':
+ return styles.eventPastSurfacePurple;
+ case 'red':
+ return styles.eventPastSurfaceRed;
+ case 'teal':
+ return styles.eventPastSurfaceTeal;
+ case 'yellow':
+ return styles.eventPastSurfaceYellow;
+ case 'blue':
+ default:
+ return styles.eventPastSurfaceBlue;
+ }
+}
+
+export function formatWithPlainDate(
+ date: PlainDate,
+ timezoneID: string,
+ options: Intl.DateTimeFormatOptions,
+): string {
+ return new Intl.DateTimeFormat(undefined, {
+ ...options,
+ timeZone: timezoneID,
+ }).format(new Date(plainDateToInstant(date, timezoneID, 12)));
+}
+
+export function formatMonthTitle(date: PlainDate, timezoneID: string): string {
+ return formatWithPlainDate(date, timezoneID, {
+ month: 'long',
+ year: 'numeric',
+ });
+}
+
+export function formatWeekTitle(
+ start: PlainDate,
+ end: PlainDate,
+ timezoneID: string,
+): string {
+ if (start.year === end.year && start.month === end.month) {
+ return formatMonthTitle(start, timezoneID);
+ }
+ const startMonth = formatWithPlainDate(start, timezoneID, {month: 'long'});
+ const endMonth = formatWithPlainDate(end, timezoneID, {month: 'long'});
+ return start.year === end.year
+ ? `${startMonth} - ${endMonth} ${end.year}`
+ : `${startMonth} ${start.year} - ${endMonth} ${end.year}`;
+}
+
+export function formatRangeTitle(
+ start: PlainDate,
+ end: PlainDate,
+ timezoneID: string,
+): string {
+ return `${formatShortDate(start, timezoneID)} - ${formatShortDate(
+ end,
+ timezoneID,
+ )}`;
+}
+
+export function formatFullDate(date: PlainDate, timezoneID: string): string {
+ return formatWithPlainDate(date, timezoneID, {
+ weekday: 'long',
+ month: 'long',
+ day: 'numeric',
+ year: 'numeric',
+ });
+}
+
+export function formatShortDate(date: PlainDate, timezoneID: string): string {
+ return formatWithPlainDate(date, timezoneID, {
+ month: 'short',
+ day: 'numeric',
+ });
+}
+
+export function formatWeekday(
+ date: PlainDate,
+ timezoneID: string,
+ weekday: 'short' | 'long',
+): string {
+ return formatWithPlainDate(date, timezoneID, {weekday});
+}
+
+export function formatDayNumber(date: PlainDate, timezoneID: string): string {
+ return formatWithPlainDate(date, timezoneID, {day: 'numeric'});
+}
+
+export function formatHour(hour: number): string {
+ return new Intl.DateTimeFormat(undefined, {
+ hour: 'numeric',
+ timeZone: 'UTC',
+ }).format(new Date(Date.UTC(2026, 0, 1, hour)));
+}
+
+export function formatTimezoneAbbreviation(
+ date: PlainDate,
+ timezoneID: string,
+): string {
+ const part = new Intl.DateTimeFormat(undefined, {
+ timeZone: timezoneID,
+ timeZoneName: 'short',
+ })
+ .formatToParts(new Date(plainDateToInstant(date, timezoneID, 12)))
+ .find(({type}) => type === 'timeZoneName');
+ return part?.value ?? timezoneID;
+}
+
+export function formatEventTime(
+ event: CalendarInstantEvent,
+ day: PlainDate,
+ timezoneID: string,
+): string {
+ const formatter = new Intl.DateTimeFormat(undefined, {
+ hour: 'numeric',
+ minute: '2-digit',
+ timeZone: timezoneID,
+ });
+ return `${formatter.format(new Date(event.start))} - ${formatter.format(
+ new Date(event.end),
+ )}`;
+}
+
+export function formatEventTimeRange(
+ event: CalendarInstantEvent,
+ timezoneID: string,
+): string {
+ const formatter = new Intl.DateTimeFormat(undefined, {
+ hour: 'numeric',
+ minute: '2-digit',
+ timeZone: timezoneID,
+ });
+ return `${formatter.format(new Date(event.start))} - ${formatter.format(
+ new Date(event.end),
+ )}`;
+}
+
+export function formatEventStartTime(
+ event: CalendarInstantEvent,
+ timezoneID: string,
+): string {
+ return new Intl.DateTimeFormat(undefined, {
+ hour: 'numeric',
+ minute: '2-digit',
+ timeZone: timezoneID,
+ }).format(new Date(event.start));
+}
+
+export function formatEventAccessibilityLabel(
+ event: CalendarEvent,
+ day: PlainDate,
+ timezoneID: string,
+ categories: ReadonlyArray<XDSScheduleCategory>,
+): string {
+ const category = getEventCategory(event, categories);
+ const timeLabel = isDayEvent(event)
+ ? 'all day'
+ : formatEventTime(event, day, timezoneID);
+ return `${event.title}, ${category.label}, ${timeLabel}`;
+}
+
+export function getMinutesSinceStartOfDay(
+ instant: number,
+ timezoneID: string,
+): number {
+ const parts = new Intl.DateTimeFormat('en-US', {
+ timeZone: timezoneID,
+ hour: '2-digit',
+ minute: '2-digit',
+ hourCycle: 'h23',
+ }).formatToParts(new Date(instant));
+ const lookup = Object.fromEntries(
+ parts
+ .filter(part => part.type !== 'literal')
+ .map(part => [part.type, Number(part.value)]),
+ );
+ return lookup.hour * 60 + lookup.minute;
+}
+
+export function clamp(value: number, min: number, max: number): number {
+ return Math.min(max, Math.max(min, value));
+}
+
+export function eventSpansPastDay(
+ event: CalendarInstantEvent,
+ day: PlainDate,
+ timezoneID: string,
+): boolean {
+ return plainDateIsAfter(
+ plainDateFromInstant(Math.max(event.end - 1, event.start), timezoneID),
+ day,
+ );
+}
+
+export function isEventInPast(
+ event: CalendarEvent,
+ currentTime: Instant,
+ timezoneID: string,
+): boolean {
+ if (isDayEvent(event)) {
+ return plainDateIsBefore(
+ event.end,
+ plainDateFromInstant(currentTime, timezoneID),
+ );
+ }
+ return event.end <= currentTime;
+}
+
+const baseText = {
+ fontFamily: typographyVars['--font-family-body'],
+ color: colorVars['--color-text-primary'],
+};
+
+export const styles = stylex.create({
+ root: {
+ display: 'flex',
+ flexDirection: 'column',
+ minWidth: 0,
+ minHeight: 0,
+ },
+ frame: {
+ flex: 1,
+ display: 'flex',
+ flexDirection: 'column',
+ minWidth: 0,
+ minHeight: 0,
+ borderWidth: borderVars['--border-width'],
+ borderStyle: 'solid',
+ borderColor: colorVars['--color-border'],
+ borderRadius: radiusVars['--radius-container'],
+ backgroundColor: colorVars['--color-background-card'],
+ overflow: 'hidden',
+ },
+ header: {
+ display: 'grid',
+ gridTemplateColumns: 'minmax(0, 1fr) auto minmax(0, 1fr)',
+ alignItems: 'center',
+ gap: spacingVars['--spacing-3'],
+ paddingBlock: spacingVars['--spacing-3'],
+ paddingInline: spacingVars['--spacing-4'],
+ borderBottomWidth: borderVars['--border-width'],
+ borderBottomStyle: 'solid',
+ borderBottomColor: colorVars['--color-border'],
+ },
+ headerControls: {
+ justifySelf: 'start',
+ },
+ headerTitle: {
+ justifySelf: 'center',
+ textAlign: 'center',
+ minWidth: 0,
+ },
+ headerTitleContent: {
+ display: 'inline-flex',
+ alignItems: 'center',
+ gap: spacingVars['--spacing-2'],
+ },
+ loadingSpinner: {
+ display: 'inline-flex',
+ },
+ loadingSpinnerHidden: {
+ visibility: 'hidden',
+ },
+ headerStatus: {
+ justifySelf: 'end',
+ minWidth: 0,
+ },
+ titleEmphasis: {
+ fontWeight: fontWeightVars['--font-weight-bold'],
+ },
+ visuallyHidden: {
+ position: 'absolute',
+ width: '1px',
+ height: '1px',
+ padding: 0,
+ margin: '-1px',
+ overflow: 'hidden',
+ clip: 'rect(0 0 0 0)',
+ whiteSpace: 'nowrap',
+ borderWidth: 0,
+ },
+ weekHeader: {
+ display: 'grid',
+ gridTemplateColumns: 'repeat(7, minmax(0, 1fr))',
+ borderBottomWidth: borderVars['--border-width'],
+ borderBottomStyle: 'solid',
+ borderBottomColor: colorVars['--color-border'],
+ },
+ weekdayLabel: {
+ paddingBlock: spacingVars['--spacing-2'],
+ paddingInline: spacingVars['--spacing-3'],
+ textAlign: 'center',
+ },
+ weekdayHeading: {
+ textAlign: 'center',
+ },
+ monthGrid: {
+ overflowX: 'auto',
+ },
+ monthGridSurface: {
+ position: 'relative',
+ width: '100%',
+ minWidth: '784px',
+ },
+ monthCellGrid: {
+ display: 'grid',
+ gridTemplateColumns: 'repeat(7, minmax(0, 1fr))',
+ gridAutoRows: '128px',
+ },
+ monthGridRow: {
+ display: 'contents',
+ },
+ monthEventOverlay: {
+ position: 'absolute',
+ inset: 0,
+ display: 'grid',
+ gridTemplateColumns: 'repeat(7, minmax(0, 1fr))',
+ gridAutoRows: '128px',
+ pointerEvents: 'none',
+ },
+ monthCell: {
+ display: 'flex',
+ flexDirection: 'column',
+ gap: spacingVars['--spacing-1'],
+ minWidth: 0,
+ padding: 0,
+ borderInlineEndWidth: borderVars['--border-width'],
+ borderInlineEndStyle: 'solid',
+ borderInlineEndColor: colorVars['--color-border'],
+ borderBlockEndWidth: borderVars['--border-width'],
+ borderBlockEndStyle: 'solid',
+ borderBlockEndColor: colorVars['--color-border'],
+ backgroundColor: colorVars['--color-background-card'],
+ },
+ monthCellLastColumn: {
+ borderInlineEndWidth: 0,
+ },
+ monthCellLastRow: {
+ borderBlockEndWidth: 0,
+ },
+ monthCellOutside: {
+ backgroundColor: colorVars['--color-background-muted'],
+ },
+ monthDayNumber: {
+ alignSelf: 'flex-start',
+ display: 'inline-flex',
+ alignItems: 'center',
+ justifyContent: 'flex-start',
+ width: '24px',
+ height: '24px',
+ margin: spacingVars['--spacing-0-5'],
+ paddingInlineStart: spacingVars['--spacing-1'],
+ paddingInlineEnd: 0,
+ borderRadius: radiusVars['--radius-full'],
+ color: colorVars['--color-text-secondary'],
+ },
+ currentDayPill: {
+ color: colorVars['--color-on-accent'],
+ backgroundColor: colorVars['--color-accent'],
+ },
+ monthEventStack: {
+ display: 'flex',
+ flexDirection: 'column',
+ gap: spacingVars['--spacing-0-5'],
+ minWidth: 0,
+ },
+ monthEventSpan: (
+ week: number,
+ columnStart: number,
+ columnEnd: number,
+ level: number,
+ ) => ({
+ gridRow: `${week + 1}`,
+ gridColumn: `${columnStart + 1} / ${columnEnd + 2}`,
+ alignSelf: 'start',
+ minWidth: 0,
+ marginInlineStart: spacingVars['--spacing-0-5'],
+ marginInlineEnd: `calc(${spacingVars['--spacing-0-5']} + ${borderVars['--border-width']})`,
+ marginBlockStart: `${30 + level * 29}px`,
+ pointerEvents: 'auto',
+ zIndex: 1,
+ }),
+ eventPill: {
+ ...baseText,
+ display: 'flex',
+ alignItems: 'center',
+ gap: spacingVars['--spacing-1'],
+ minWidth: 0,
+ borderWidth: borderVars['--border-width'],
+ borderStyle: 'solid',
+ borderRadius: radiusVars['--radius-inner'],
+ paddingBlock: spacingVars['--spacing-0-5'],
+ paddingInline: spacingVars['--spacing-1-5'],
+ fontSize: typeScaleVars['--text-supporting-size'],
+ lineHeight: typeScaleVars['--text-supporting-leading'],
+ fontWeight: fontWeightVars['--font-weight-medium'],
+ },
+ eventTitle: {
+ overflow: 'hidden',
+ textOverflow: 'ellipsis',
+ whiteSpace: 'nowrap',
+ minWidth: 0,
+ },
+ eventTime: {
+ overflow: 'hidden',
+ textOverflow: 'ellipsis',
+ whiteSpace: 'nowrap',
+ flexShrink: 0,
+ opacity: 0.8,
+ },
+ moreEvents: {
+ ...baseText,
+ color: colorVars['--color-text-secondary'],
+ fontSize: typeScaleVars['--text-supporting-size'],
+ lineHeight: typeScaleVars['--text-supporting-leading'],
+ },
+ timeGrid: {
+ flex: 1,
+ display: 'grid',
+ gridTemplateColumns: '60px minmax(0, 1fr)',
+ gridTemplateRows: '56px auto 1fr',
+ height: '640px',
+ minHeight: 0,
+ overflow: 'hidden',
+ },
+ timeGridCorner: {
+ gridColumn: 1,
+ gridRow: 1,
+ borderInlineEndWidth: borderVars['--border-width'],
+ borderInlineEndStyle: 'solid',
+ borderInlineEndColor: colorVars['--color-border'],
+ borderBottomWidth: borderVars['--border-width'],
+ borderBottomStyle: 'solid',
+ borderBottomColor: colorVars['--color-border'],
+ },
+ timeGridHeader: {
+ gridColumn: 2,
+ gridRow: 1,
+ display: 'grid',
+ gridAutoFlow: 'column',
+ gridAutoColumns: 'minmax(140px, 1fr)',
+ borderBottomWidth: borderVars['--border-width'],
+ borderBottomStyle: 'solid',
+ borderBottomColor: colorVars['--color-border'],
+ },
+ timeGridHeaderCell: {
+ display: 'flex',
+ flexDirection: 'column',
+ alignItems: 'center',
+ justifyContent: 'center',
+ gap: spacingVars['--spacing-0-5'],
+ borderInlineEndWidth: borderVars['--border-width'],
+ borderInlineEndStyle: 'solid',
+ borderInlineEndColor: colorVars['--color-border'],
+ },
+ timeGridHeaderCellLast: {
+ borderInlineEndWidth: 0,
+ },
+ timeGridHeaderHeading: {
+ textAlign: 'center',
+ },
+ timeGridHeaderHeadingContent: {
+ display: 'inline-flex',
+ alignItems: 'center',
+ justifyContent: 'center',
+ gap: spacingVars['--spacing-1'],
+ },
+ timeGridDayNumber: {
+ display: 'inline-flex',
+ alignItems: 'center',
+ justifyContent: 'center',
+ borderRadius: radiusVars['--radius-full'],
+ },
+ timeGridCurrentDayPill: {
+ minWidth: '30px',
+ height: '30px',
+ lineHeight: '30px',
+ color: colorVars['--color-on-accent'],
+ backgroundColor: colorVars['--color-accent'],
+ },
+ allDayLabel: {
+ gridColumn: 1,
+ gridRow: 2,
+ paddingBlock: spacingVars['--spacing-1'],
+ paddingInline: spacingVars['--spacing-2'],
+ display: 'flex',
+ alignItems: 'center',
+ justifyContent: 'flex-end',
+ borderInlineEndWidth: borderVars['--border-width'],
+ borderInlineEndStyle: 'solid',
+ borderInlineEndColor: colorVars['--color-border'],
+ borderBottomWidth: borderVars['--border-width'],
+ borderBottomStyle: 'solid',
+ borderBottomColor: colorVars['--color-border'],
+ },
+ allDayRow: {
+ gridColumn: 2,
+ gridRow: 2,
+ overflowX: 'auto',
+ minHeight: 0,
+ borderBottomWidth: borderVars['--border-width'],
+ borderBottomStyle: 'solid',
+ borderBottomColor: colorVars['--color-border'],
+ },
+ allDayRowSurface: (columnCount: number, levelCount: number) => ({
+ position: 'relative',
+ width: '100%',
+ minWidth: `${Math.max(1, columnCount) * 140}px`,
+ minHeight: levelCount > 0 ? `${3 + levelCount * 27}px` : '26px',
+ }),
+ allDayCellGrid: (columnCount: number) => ({
+ position: 'absolute',
+ inset: 0,
+ display: 'grid',
+ gridTemplateColumns: `repeat(${Math.max(1, columnCount)}, minmax(0, 1fr))`,
+ }),
+ allDayEventOverlay: (columnCount: number) => ({
+ position: 'absolute',
+ inset: 0,
+ display: 'grid',
+ gridTemplateColumns: `repeat(${Math.max(1, columnCount)}, minmax(0, 1fr))`,
+ pointerEvents: 'none',
+ }),
+ allDayCell: {
+ minWidth: 0,
+ borderInlineEndWidth: borderVars['--border-width'],
+ borderInlineEndStyle: 'solid',
+ borderInlineEndColor: colorVars['--color-border'],
+ },
+ allDayCellLast: {
+ borderInlineEndWidth: 0,
+ },
+ allDayEventSpan: (columnStart: number, columnEnd: number, level: number) => ({
+ gridColumn: `${columnStart + 1} / ${columnEnd + 2}`,
+ alignSelf: 'start',
+ minWidth: 0,
+ marginInlineStart: spacingVars['--spacing-0-5'],
+ marginInlineEnd: `calc(${spacingVars['--spacing-0-5']} + ${borderVars['--border-width']})`,
+ marginBlockStart: `${2 + level * 27}px`,
+ pointerEvents: 'auto',
+ }),
+ timeGridBody: {
+ gridColumn: '1 / -1',
+ gridRow: 3,
+ display: 'grid',
+ gridTemplateColumns: '60px minmax(0, 1fr)',
+ overflow: 'auto',
+ minHeight: 0,
+ },
+ timeLabels: {
+ gridColumn: 1,
+ position: 'relative',
+ borderInlineEndWidth: borderVars['--border-width'],
+ borderInlineEndStyle: 'solid',
+ borderInlineEndColor: colorVars['--color-border'],
+ },
+ timeLabel: {
+ ...baseText,
+ position: 'absolute',
+ insetInline: 0,
+ transform: 'translateY(-50%)',
+ paddingInlineStart: spacingVars['--spacing-1'],
+ paddingInlineEnd: spacingVars['--spacing-1'],
+ color: colorVars['--color-text-secondary'],
+ fontSize: typeScaleVars['--text-supporting-size'],
+ lineHeight: typeScaleVars['--text-supporting-leading'],
+ textAlign: 'end',
+ },
+ timeLabelPosition: (index: number, hourHeight: number) => ({
+ top: `${index * hourHeight - 1}px`,
+ }),
+ timeColumns: {
+ gridColumn: 2,
+ display: 'grid',
+ gridAutoFlow: 'column',
+ gridAutoColumns: 'minmax(140px, 1fr)',
+ minWidth: 0,
+ },
+ timeColumn: {
+ position: 'relative',
+ display: 'grid',
+ minWidth: 0,
+ borderInlineEndWidth: borderVars['--border-width'],
+ borderInlineEndStyle: 'solid',
+ borderInlineEndColor: colorVars['--color-border'],
+ },
+ timeColumnRows: (hourHeight: number) => ({
+ gridAutoRows: `${hourHeight}px`,
+ }),
+ timeColumnLast: {
+ borderInlineEndWidth: 0,
+ },
+ hourSlot: {
+ borderBottomWidth: borderVars['--border-width'],
+ borderBottomStyle: 'solid',
+ borderBottomColor: colorVars['--color-border'],
+ },
+ hourSlotLast: {
+ borderBottomWidth: 0,
+ },
+ timedEvent: {
+ ...baseText,
+ position: 'absolute',
+ display: 'flex',
+ flexDirection: 'column',
+ gap: 0,
+ minHeight: '24px',
+ minWidth: 0,
+ overflow: 'hidden',
+ borderWidth: borderVars['--border-width'],
+ borderStyle: 'solid',
+ borderRadius: radiusVars['--radius-inner'],
+ paddingBlockStart: spacingVars['--spacing-0-5'],
+ paddingBlockEnd: spacingVars['--spacing-1'],
+ paddingInline: spacingVars['--spacing-1'],
+ fontSize: typeScaleVars['--text-supporting-size'],
+ lineHeight: typeScaleVars['--text-supporting-leading'],
+ fontWeight: fontWeightVars['--font-weight-medium'],
+ },
+ timedEventPosition: (top: number, height: number, level: number) => ({
+ top: `calc(${top}% + 2px)`,
+ height: `calc(${height}% - 5px)`,
+ insetInlineStart:
+ level === 0
+ ? spacingVars['--spacing-0-5']
+ : `calc(${spacingVars['--spacing-0-5']} + ${level * 8}%)`,
+ insetInlineEnd: spacingVars['--spacing-0-5'],
+ zIndex: level + 1,
+ }),
+ currentTimeLine: (top: number) => ({
+ position: 'absolute',
+ insetInline: 0,
+ top: `calc(${top}% + 2px)`,
+ borderTopWidth: '2px',
+ borderTopStyle: 'solid',
+ borderTopColor: colorVars['--color-border-orange'],
+ zIndex: 20,
+ pointerEvents: 'none',
+ '::before': {
+ content: '""',
+ position: 'absolute',
+ insetInlineStart: '-6px',
+ top: '-6px',
+ width: '10px',
+ height: '10px',
+ borderRadius: radiusVars['--radius-full'],
+ backgroundColor: colorVars['--color-border-orange'],
+ },
+ }),
+ list: {
+ display: 'flex',
+ flexDirection: 'column',
+ },
+ listDay: {
+ display: 'grid',
+ gridTemplateColumns: '88px minmax(0, 1fr)',
+ alignItems: 'start',
+ columnGap: spacingVars['--spacing-3'],
+ paddingBlock: spacingVars['--spacing-3'],
+ paddingInline: spacingVars['--spacing-3'],
+ borderBottomWidth: borderVars['--border-width'],
+ borderBottomStyle: 'solid',
+ borderBottomColor: colorVars['--color-border'],
+ },
+ listDayLast: {
+ borderBottomWidth: 0,
+ },
+ listDayHeading: {
+ gridColumn: '1',
+ display: 'inline-flex',
+ alignItems: 'center',
+ justifyContent: 'flex-start',
+ columnGap: spacingVars['--spacing-2'],
+ marginBlockStart: `calc(${spacingVars['--spacing-1']} * -1)`,
+ marginInlineStart: `calc(${spacingVars['--spacing-1']} * -1)`,
+ },
+ listDayNumber: {
+ display: 'inline-flex',
+ alignItems: 'center',
+ justifyContent: 'flex-end',
+ width: '30px',
+ height: '30px',
+ borderRadius: radiusVars['--radius-full'],
+ },
+ listDayNumberText: {
+ fontWeight: fontWeightVars['--font-weight-bold'],
+ },
+ listDayNumberCurrent: {
+ justifyContent: 'center',
+ color: colorVars['--color-on-accent'],
+ backgroundColor: colorVars['--color-accent'],
+ },
+ listEvents: {
+ gridColumn: 2,
+ display: 'flex',
+ flexDirection: 'column',
+ gap: spacingVars['--spacing-2'],
+ minWidth: 0,
+ },
+ listNowRow: {
+ position: 'relative',
+ height: '10px',
+ marginBlock: spacingVars['--spacing-0-5'],
+ '::before': {
+ content: '""',
+ position: 'absolute',
+ insetInline: 0,
+ top: '4px',
+ borderTopWidth: '2px',
+ borderTopStyle: 'solid',
+ borderTopColor: colorVars['--color-border-orange'],
+ },
+ '::after': {
+ content: '""',
+ position: 'absolute',
+ insetInlineStart: '-1px',
+ top: 0,
+ width: '10px',
+ height: '10px',
+ borderRadius: radiusVars['--radius-full'],
+ backgroundColor: colorVars['--color-border-orange'],
+ },
+ },
+ listEventRow: {
+ display: 'grid',
+ gridTemplateColumns: '12px 144px minmax(0, 1fr)',
+ alignItems: 'center',
+ gap: spacingVars['--spacing-2'],
+ minWidth: 0,
+ },
+ listEventDot: {
+ width: '10px',
+ height: '10px',
+ borderRadius: radiusVars['--radius-full'],
+ },
+ listEventTime: {
+ ...baseText,
+ color: colorVars['--color-text-secondary'],
+ fontSize: typeScaleVars['--text-supporting-size'],
+ lineHeight: typeScaleVars['--text-supporting-leading'],
+ whiteSpace: 'nowrap',
+ },
+ listEventTitle: {
+ ...baseText,
+ minWidth: 0,
+ overflow: 'hidden',
+ textOverflow: 'ellipsis',
+ whiteSpace: 'nowrap',
+ fontSize: typeScaleVars['--text-body-size'],
+ lineHeight: typeScaleVars['--text-body-leading'],
+ fontWeight: fontWeightVars['--font-weight-medium'],
+ },
+ listEventPast: {
+ opacity: 0.5,
+ },
+ eventBlue: {
+ color: colorVars['--color-text-blue'],
+ backgroundColor: colorVars['--color-background-blue'],
+ borderColor: colorVars['--color-border-blue'],
+ },
+ eventDotBlue: {
+ backgroundColor: colorVars['--color-border-blue'],
+ },
+ eventSurfaceBlue: {
+ color: colorVars['--color-text-blue'],
+ borderColor: colorVars['--color-border-blue'],
+ backgroundColor: `color-mix(in srgb, ${colorVars['--color-border-blue']} 20%, ${colorVars['--color-background-card']})`,
+ },
+ eventPastSurfaceBlue: {
+ color: `color-mix(in srgb, ${colorVars['--color-text-blue']} 52%, ${colorVars['--color-text-secondary']})`,
+ borderColor: `color-mix(in srgb, ${colorVars['--color-border-blue']} 48%, ${colorVars['--color-border']})`,
+ backgroundColor: `color-mix(in srgb, ${colorVars['--color-border-blue']} 10%, ${colorVars['--color-background-card']})`,
+ },
+ eventCyan: {
+ color: colorVars['--color-text-cyan'],
+ backgroundColor: colorVars['--color-background-cyan'],
+ borderColor: colorVars['--color-border-cyan'],
+ },
+ eventDotCyan: {
+ backgroundColor: colorVars['--color-border-cyan'],
+ },
+ eventSurfaceCyan: {
+ color: colorVars['--color-text-cyan'],
+ borderColor: colorVars['--color-border-cyan'],
+ backgroundColor: `color-mix(in srgb, ${colorVars['--color-border-cyan']} 20%, ${colorVars['--color-background-card']})`,
+ },
+ eventPastSurfaceCyan: {
+ color: `color-mix(in srgb, ${colorVars['--color-text-cyan']} 52%, ${colorVars['--color-text-secondary']})`,
+ borderColor: `color-mix(in srgb, ${colorVars['--color-border-cyan']} 48%, ${colorVars['--color-border']})`,
+ backgroundColor: `color-mix(in srgb, ${colorVars['--color-border-cyan']} 10%, ${colorVars['--color-background-card']})`,
+ },
+ eventGray: {
+ color: colorVars['--color-text-gray'],
+ backgroundColor: colorVars['--color-background-gray'],
+ borderColor: colorVars['--color-border-gray'],
+ },
+ eventDotGray: {
+ backgroundColor: colorVars['--color-text-secondary'],
+ },
+ eventSurfaceGray: {
+ color: colorVars['--color-text-gray'],
+ borderColor: colorVars['--color-border-gray'],
+ backgroundColor: `color-mix(in srgb, ${colorVars['--color-border-gray']} 20%, ${colorVars['--color-background-card']})`,
+ },
+ eventPastSurfaceGray: {
+ color: colorVars['--color-text-secondary'],
+ borderColor: colorVars['--color-border'],
+ backgroundColor: `color-mix(in srgb, ${colorVars['--color-border-gray']} 10%, ${colorVars['--color-background-card']})`,
+ },
+ eventGreen: {
+ color: colorVars['--color-text-green'],
+ backgroundColor: colorVars['--color-background-green'],
+ borderColor: colorVars['--color-border-green'],
+ },
+ eventDotGreen: {
+ backgroundColor: colorVars['--color-border-green'],
+ },
+ eventSurfaceGreen: {
+ color: colorVars['--color-text-green'],
+ borderColor: colorVars['--color-border-green'],
+ backgroundColor: `color-mix(in srgb, ${colorVars['--color-border-green']} 20%, ${colorVars['--color-background-card']})`,
+ },
+ eventPastSurfaceGreen: {
+ color: `color-mix(in srgb, ${colorVars['--color-text-green']} 52%, ${colorVars['--color-text-secondary']})`,
+ borderColor: `color-mix(in srgb, ${colorVars['--color-border-green']} 48%, ${colorVars['--color-border']})`,
+ backgroundColor: `color-mix(in srgb, ${colorVars['--color-border-green']} 10%, ${colorVars['--color-background-card']})`,
+ },
+ eventOrange: {
+ color: colorVars['--color-text-orange'],
+ backgroundColor: colorVars['--color-background-orange'],
+ borderColor: colorVars['--color-border-orange'],
+ },
+ eventDotOrange: {
+ backgroundColor: colorVars['--color-border-orange'],
+ },
+ eventSurfaceOrange: {
+ color: colorVars['--color-text-orange'],
+ borderColor: colorVars['--color-border-orange'],
+ backgroundColor: `color-mix(in srgb, ${colorVars['--color-border-orange']} 20%, ${colorVars['--color-background-card']})`,
+ },
+ eventPastSurfaceOrange: {
+ color: `color-mix(in srgb, ${colorVars['--color-text-orange']} 52%, ${colorVars['--color-text-secondary']})`,
+ borderColor: `color-mix(in srgb, ${colorVars['--color-border-orange']} 48%, ${colorVars['--color-border']})`,
+ backgroundColor: `color-mix(in srgb, ${colorVars['--color-border-orange']} 10%, ${colorVars['--color-background-card']})`,
+ },
+ eventPink: {
+ color: colorVars['--color-text-pink'],
+ backgroundColor: colorVars['--color-background-pink'],
+ borderColor: colorVars['--color-border-pink'],
+ },
+ eventDotPink: {
+ backgroundColor: colorVars['--color-border-pink'],
+ },
+ eventSurfacePink: {
+ color: colorVars['--color-text-pink'],
+ borderColor: colorVars['--color-border-pink'],
+ backgroundColor: `color-mix(in srgb, ${colorVars['--color-border-pink']} 20%, ${colorVars['--color-background-card']})`,
+ },
+ eventPastSurfacePink: {
+ color: `color-mix(in srgb, ${colorVars['--color-text-pink']} 52%, ${colorVars['--color-text-secondary']})`,
+ borderColor: `color-mix(in srgb, ${colorVars['--color-border-pink']} 48%, ${colorVars['--color-border']})`,
+ backgroundColor: `color-mix(in srgb, ${colorVars['--color-border-pink']} 10%, ${colorVars['--color-background-card']})`,
+ },
+ eventPurple: {
+ color: colorVars['--color-text-purple'],
+ backgroundColor: colorVars['--color-background-purple'],
+ borderColor: colorVars['--color-border-purple'],
+ },
+ eventDotPurple: {
+ backgroundColor: colorVars['--color-border-purple'],
+ },
+ eventSurfacePurple: {
+ color: colorVars['--color-text-purple'],
+ borderColor: colorVars['--color-border-purple'],
+ backgroundColor: `color-mix(in srgb, ${colorVars['--color-border-purple']} 20%, ${colorVars['--color-background-card']})`,
+ },
+ eventPastSurfacePurple: {
+ color: `color-mix(in srgb, ${colorVars['--color-text-purple']} 52%, ${colorVars['--color-text-secondary']})`,
+ borderColor: `color-mix(in srgb, ${colorVars['--color-border-purple']} 48%, ${colorVars['--color-border']})`,
+ backgroundColor: `color-mix(in srgb, ${colorVars['--color-border-purple']} 10%, ${colorVars['--color-background-card']})`,
+ },
+ eventRed: {
+ color: colorVars['--color-text-red'],
+ backgroundColor: colorVars['--color-background-red'],
+ borderColor: colorVars['--color-border-red'],
+ },
+ eventDotRed: {
+ backgroundColor: colorVars['--color-border-red'],
+ },
+ eventSurfaceRed: {
+ color: colorVars['--color-text-red'],
+ borderColor: colorVars['--color-border-red'],
+ backgroundColor: `color-mix(in srgb, ${colorVars['--color-border-red']} 20%, ${colorVars['--color-background-card']})`,
+ },
+ eventPastSurfaceRed: {
+ color: `color-mix(in srgb, ${colorVars['--color-text-red']} 52%, ${colorVars['--color-text-secondary']})`,
+ borderColor: `color-mix(in srgb, ${colorVars['--color-border-red']} 48%, ${colorVars['--color-border']})`,
+ backgroundColor: `color-mix(in srgb, ${colorVars['--color-border-red']} 10%, ${colorVars['--color-background-card']})`,
+ },
+ eventTeal: {
+ color: colorVars['--color-text-teal'],
+ backgroundColor: colorVars['--color-background-teal'],
+ borderColor: colorVars['--color-border-teal'],
+ },
+ eventDotTeal: {
+ backgroundColor: colorVars['--color-border-teal'],
+ },
+ eventSurfaceTeal: {
+ color: colorVars['--color-text-teal'],
+ borderColor: colorVars['--color-border-teal'],
+ backgroundColor: `color-mix(in srgb, ${colorVars['--color-border-teal']} 20%, ${colorVars['--color-background-card']})`,
+ },
+ eventPastSurfaceTeal: {
+ color: `color-mix(in srgb, ${colorVars['--color-text-teal']} 52%, ${colorVars['--color-text-secondary']})`,
+ borderColor: `color-mix(in srgb, ${colorVars['--color-border-teal']} 48%, ${colorVars['--color-border']})`,
+ backgroundColor: `color-mix(in srgb, ${colorVars['--color-border-teal']} 10%, ${colorVars['--color-background-card']})`,
+ },
+ eventYellow: {
+ color: colorVars['--color-text-yellow'],
+ backgroundColor: colorVars['--color-background-yellow'],
+ borderColor: colorVars['--color-border-yellow'],
+ },
+ eventDotYellow: {
+ backgroundColor: colorVars['--color-border-yellow'],
+ },
+ eventSurfaceYellow: {
+ color: colorVars['--color-text-yellow'],
+ borderColor: colorVars['--color-border-yellow'],
+ backgroundColor: `color-mix(in srgb, ${colorVars['--color-border-yellow']} 20%, ${colorVars['--color-background-card']})`,
+ },
+ eventPastSurfaceYellow: {
+ color: `color-mix(in srgb, ${colorVars['--color-text-yellow']} 52%, ${colorVars['--color-text-secondary']})`,
+ borderColor: `color-mix(in srgb, ${colorVars['--color-border-yellow']} 48%, ${colorVars['--color-border']})`,
+ backgroundColor: `color-mix(in srgb, ${colorVars['--color-border-yellow']} 10%, ${colorVars['--color-background-card']})`,
+ },
+});
diff --git a/packages/lab/src/Schedule/types.ts b/packages/lab/src/Schedule/types.ts
new file mode 100644
index 0000000000..ab8ec70e8a
--- /dev/null
+++ b/packages/lab/src/Schedule/types.ts
@@ -0,0 +1,86 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file types.ts
+ * @input Public XDSSchedule API concepts
+ * @output Event, view, date, loader, and context types for XDSSchedule
+ * @position Public type surface; consumed by Schedule implementation and exports
+ */
+
+import type {ReactNode} from 'react';
+import type {PlainDate} from '@xds/core/utils';
+import type {CalendarEvent} from './CalendarEvent';
+import type {ZonedDateTime, ZonedDateTimeRange} from './zonedDateTime';
+
+export type {PlainDate} from '@xds/core/utils';
+export type {
+ CalendarDayEvent,
+ CalendarEvent,
+ CalendarEventBase,
+ CalendarInstantEvent,
+ XDSScheduleCategory,
+ XDSScheduleEventColor,
+} from './CalendarEvent';
+export type {ZonedDateTime, ZonedDateTimeRange} from './zonedDateTime';
+
+/** Unix epoch milliseconds. */
+export type Instant = number;
+
+export type XDSScheduleEventSource =
+ | ReadonlyArray<CalendarEvent>
+ | ((start: Instant, end: Instant) => Promise<ReadonlyArray<CalendarEvent>>);
+
+export type XDSScheduleDate = Instant;
+
+export interface ScheduleRange {
+ startDate: PlainDate;
+ endDate: PlainDate;
+ start: Instant;
+ end: Instant;
+}
+
+export type XDSScheduleViewOptions = object;
+
+export interface XDSScheduleViewComponentProps<
+ Options extends XDSScheduleViewOptions = XDSScheduleViewOptions,
+> {
+ options: Options;
+}
+
+export interface XDSScheduleNavigationRange {
+ label: string;
+ range: ZonedDateTimeRange;
+}
+
+export type XDSScheduleViewComponent<
+ Options extends XDSScheduleViewOptions = XDSScheduleViewOptions,
+> = (props: XDSScheduleViewComponentProps<Options>) => ReactNode;
+
+export interface XDSScheduleViewBase {
+ getDateRange: (date: ZonedDateTime) => ZonedDateTimeRange;
+ getPreviousDateRange: (date: ZonedDateTime) => XDSScheduleNavigationRange;
+ getNextDateRange: (date: ZonedDateTime) => XDSScheduleNavigationRange;
+}
+
+export interface XDSScheduleView<
+ Options extends XDSScheduleViewOptions = XDSScheduleViewOptions,
+> extends XDSScheduleViewBase {
+ component: XDSScheduleViewComponent<Options>;
+ options: Options;
+}
+
+export interface XDSScheduleHeaderContent {
+ startContent: ReactNode;
+ centerContent: ReactNode;
+ endContent: ReactNode;
+}
+
+export type XDSSchedulePluginPosition = 'start' | 'end';
+
+export interface XDSSchedulePlugin {
+ renderHeader?: (
+ startContent: ReactNode,
+ centerContent: ReactNode,
+ endContent: ReactNode,
+ ) => XDSScheduleHeaderContent;
+}
diff --git a/packages/lab/src/Schedule/useCurrentTime.ts b/packages/lab/src/Schedule/useCurrentTime.ts
new file mode 100644
index 0000000000..d2a5355c13
--- /dev/null
+++ b/packages/lab/src/Schedule/useCurrentTime.ts
@@ -0,0 +1,50 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useCurrentTime.ts
+ * @input Browser clock
+ * @output A shared ticking Instant value for schedule current-time affordances
+ * @position Internal hook consumed by schedule views
+ */
+
+import {useSyncExternalStore} from 'react';
+import type {Instant} from './types';
+
+const UPDATE_INTERVAL_MS = 60 * 1000;
+const listeners = new Set<() => void>();
+let interval: ReturnType<typeof setInterval> | null = null;
+let currentTime = Date.now() as Instant;
+
+function getSnapshot(): Instant {
+ return currentTime;
+}
+
+// SSR returns 0 because current time only drives client-side affordances
+// (now-indicator line, past-event dimming) that are acceptable to hydrate.
+function getServerSnapshot(): Instant {
+ return 0 as Instant;
+}
+
+function subscribe(listener: () => void): () => void {
+ listeners.add(listener);
+ if (interval == null) {
+ interval = setInterval(() => {
+ currentTime = Date.now() as Instant;
+ listeners.forEach(activeListener => activeListener());
+ }, UPDATE_INTERVAL_MS);
+ }
+
+ return () => {
+ listeners.delete(listener);
+ if (listeners.size === 0 && interval != null) {
+ clearInterval(interval);
+ interval = null;
+ }
+ };
+}
+
+export function useCurrentTime(): Instant {
+ return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+}
diff --git a/packages/lab/src/Schedule/zonedDateTime.ts b/packages/lab/src/Schedule/zonedDateTime.ts
new file mode 100644
index 0000000000..302b962256
--- /dev/null
+++ b/packages/lab/src/Schedule/zonedDateTime.ts
@@ -0,0 +1,71 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file zonedDateTime.ts
+ * @input Instant epoch milliseconds and IANA timezone IDs
+ * @output Lightweight ZonedDateTime helpers used by XDSSchedule views
+ * @position Internal timezone-aware date bridge between schedule shell and views
+ */
+
+import {
+ plainDateAddDays,
+ plainDateFromInstant,
+ plainDateToInstant,
+ type PlainDate,
+} from '@xds/core/utils';
+import type {Instant, ScheduleRange, XDSScheduleDate} from './types';
+
+export interface ZonedDateTime {
+ instant: Instant;
+ timezoneID: string;
+ toPlainDate: () => PlainDate;
+ addDays: (days: number) => ZonedDateTime;
+ startOfDay: () => ZonedDateTime;
+}
+
+export type ZonedDateTimeRange = [ZonedDateTime, ZonedDateTime];
+
+export function createZonedDateTime(
+ date: XDSScheduleDate,
+ timezoneID: string,
+): ZonedDateTime {
+ return zonedDateTimeFromInstant(date as Instant, timezoneID);
+}
+
+export function zonedDateTimeFromInstant(
+ instant: Instant,
+ timezoneID: string,
+): ZonedDateTime {
+ return {
+ instant,
+ timezoneID,
+ toPlainDate: () => plainDateFromInstant(instant, timezoneID),
+ addDays: days => {
+ const date = plainDateAddDays(
+ plainDateFromInstant(instant, timezoneID),
+ days,
+ );
+ return zonedDateTimeFromInstant(
+ plainDateToInstant(date, timezoneID) as Instant,
+ timezoneID,
+ );
+ },
+ startOfDay: () => {
+ const date = plainDateFromInstant(instant, timezoneID);
+ return zonedDateTimeFromInstant(
+ plainDateToInstant(date, timezoneID) as Instant,
+ timezoneID,
+ );
+ },
+ };
+}
+
+export function scheduleRangeToZonedDateTimeRange(
+ range: ScheduleRange,
+ timezoneID: string,
+): ZonedDateTimeRange {
+ return [
+ zonedDateTimeFromInstant(range.start, timezoneID),
+ zonedDateTimeFromInstant(range.end, timezoneID),
+ ];
+}
diff --git a/packages/lab/src/index.ts b/packages/lab/src/index.ts
index 30e57db0f9..f235f4010c 100644
--- a/packages/lab/src/index.ts
+++ b/packages/lab/src/index.ts
@@ -26,6 +26,9 @@ export {
type XDSChatReasoningProps,
} from './ChatReasoning/XDSChatReasoning';
+// Schedule — experimental full-calendar views
+export * from './Schedule';
+
// SVG Icon system — CSS-variable-driven multi-variation icons
export {
XDSSVGIcon,