@dxos/react-ui-calendar 0.8.4-main.03d5cd7b56

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@dxos/react-ui-calendar",
+  "version": "0.8.4-main.03d5cd7b56",
+  "description": "A calendar component.",
+  "homepage": "https://dxos.org",
+  "bugs": "https://github.com/dxos/dxos/issues",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dxos/dxos"
+  },
+  "license": "MIT",
+  "author": "DXOS.org",
+  "type": "module",
+  "imports": {
+    "#translations": "./src/translations.ts"
+  },
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "types": "./dist/types/src/index.d.ts",
+      "browser": "./dist/lib/browser/index.mjs",
+      "node": "./dist/lib/node-esm/index.mjs"
+    },
+    "./translations": {
+      "source": "./src/translations.ts",
+      "types": "./dist/types/src/translations.d.ts",
+      "browser": "./dist/lib/browser/translations.mjs",
+      "node": "./dist/lib/node-esm/translations.mjs"
+    }
+  },
+  "types": "dist/types/src/index.d.ts",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "@radix-ui/react-context": "1.1.1",
+    "date-fns": "^3.6.0",
+    "react-resize-detector": "^11.0.1",
+    "react-virtualized": "^9.22.6",
+    "react-window": "^2.2.3",
+    "@dxos/invariant": "0.8.4-main.03d5cd7b56",
+    "@dxos/async": "0.8.4-main.03d5cd7b56",
+    "@dxos/debug": "0.8.4-main.03d5cd7b56",
+    "@dxos/log": "0.8.4-main.03d5cd7b56",
+    "@dxos/util": "0.8.4-main.03d5cd7b56"
+  },
+  "devDependencies": {
+    "@types/react": "~19.2.7",
+    "@types/react-dom": "~19.2.3",
+    "@types/react-virtualized": "^9.22.3",
+    "effect": "3.20.0",
+    "react": "~19.2.3",
+    "react-dom": "~19.2.3",
+    "vite": "^8.0.10",
+    "@dxos/random": "0.8.4-main.03d5cd7b56",
+    "@dxos/react-ui": "0.8.4-main.03d5cd7b56",
+    "@dxos/ui-theme": "0.8.4-main.03d5cd7b56",
+    "@dxos/storybook-utils": "0.8.4-main.03d5cd7b56"
+  },
+  "peerDependencies": {
+    "effect": "3.20.0",
+    "react": "~19.2.3",
+    "react-dom": "~19.2.3",
+    "@dxos/react-ui": "0.8.4-main.03d5cd7b56",
+    "@dxos/ui-theme": "0.8.4-main.03d5cd7b56"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/components/Calendar/Calendar.stories.tsx

@@ -0,0 +1,51 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import React from 'react';
+
+import { Panel } from '@dxos/react-ui';
+import { withLayout, withTheme } from '@dxos/react-ui/testing';
+
+import { translations } from '#translations';
+
+import { Calendar } from './Calendar';
+
+const meta = {
+  title: 'ui/react-ui-calendar/Calendar',
+  component: Calendar.Grid,
+  parameters: {
+    translations,
+  },
+} satisfies Meta<typeof Calendar.Grid>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  decorators: [withTheme(), withLayout({ layout: 'centered' })],
+  render: () => (
+    <Calendar.Root>
+      <Calendar.Toolbar />
+      <Calendar.Grid rows={6} />
+    </Calendar.Root>
+  ),
+};
+
+export const Column: Story = {
+  decorators: [withTheme(), withLayout({ layout: 'column', classNames: 'w-auto' })],
+  render: () => (
+    <Calendar.Root>
+      <Panel.Root>
+        <Panel.Toolbar asChild>
+          <Calendar.Toolbar />
+        </Panel.Toolbar>
+        <Panel.Content asChild>
+          <Calendar.Grid />
+        </Panel.Content>
+      </Panel.Root>
+    </Calendar.Root>
+  ),
+};

package/src/components/Calendar/Calendar.tsx

@@ -0,0 +1,300 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { createContext } from '@radix-ui/react-context';
+import { type Day, addDays, differenceInWeeks, format, startOfDay, startOfWeek } from 'date-fns';
+import React, {
+  type Dispatch,
+  type PropsWithChildren,
+  type SetStateAction,
+  forwardRef,
+  useCallback,
+  useEffect,
+  useImperativeHandle,
+  useMemo,
+  useRef,
+  useState,
+} from 'react';
+import { useResizeDetector } from 'react-resize-detector';
+import { List, type ListProps, type ListRowRenderer } from 'react-virtualized';
+
+import { Event } from '@dxos/async';
+import { IconButton, useTranslation } from '@dxos/react-ui';
+import { composable, composableProps, mx } from '@dxos/ui-theme';
+
+import { translationKey } from '#translations';
+
+import { getDate, isSameDay } from './util';
+
+const maxRows = 50 * 100;
+const start = new Date('1970-01-01');
+const size = 48;
+const defaultWidth = 7 * size;
+
+//
+// Context
+//
+
+type CalendarEvent = {
+  type: 'scroll';
+  date: Date;
+};
+
+type CalendarContextValue = {
+  weekStartsOn: Day;
+  event: Event<CalendarEvent>;
+  index: number | undefined;
+  setIndex: Dispatch<SetStateAction<number | undefined>>;
+  selected: Date | undefined;
+  setSelected: Dispatch<SetStateAction<Date | undefined>>;
+};
+
+const [CalendarContextProvider, useCalendarContext] = createContext<CalendarContextValue>('Calendar');
+
+//
+// Controller
+//
+
+type CalendarController = {
+  scrollTo: (date: Date) => void;
+};
+
+//
+// Root
+//
+
+type CalendarRootProps = PropsWithChildren<Partial<Pick<CalendarContextValue, 'weekStartsOn'>>>;
+
+const CalendarRoot = forwardRef<CalendarController, CalendarRootProps>(
+  ({ children, weekStartsOn = 1 }, forwardedRef) => {
+    const event = useMemo(() => new Event<CalendarEvent>(), []);
+    const [selected, setSelected] = useState<Date | undefined>();
+    const [index, setIndex] = useState<number | undefined>();
+
+    useImperativeHandle(
+      forwardedRef,
+      () => ({
+        scrollTo: (date: Date) => {
+          event.emit({ type: 'scroll', date });
+        },
+      }),
+      [event],
+    );
+
+    return (
+      <CalendarContextProvider
+        weekStartsOn={weekStartsOn}
+        event={event}
+        index={index}
+        setIndex={setIndex}
+        selected={selected}
+        setSelected={setSelected}
+      >
+        {children}
+      </CalendarContextProvider>
+    );
+  },
+);
+
+//
+// Header
+//
+
+const CALENDAR_TOOLBAR_NAME = 'CalendarHeader';
+
+type CalendarToolbarProps = {};
+
+const CalendarToolbar = composable<HTMLDivElement, CalendarToolbarProps>(({ classNames, ...props }, forwardedRef) => {
+  const { t } = useTranslation(translationKey);
+  const { weekStartsOn, event, index, selected } = useCalendarContext(CALENDAR_TOOLBAR_NAME);
+  const top = useMemo(() => getDate(start, index ?? 0, 6, weekStartsOn), [index, weekStartsOn]);
+  const today = useMemo(() => new Date(), []);
+
+  const handleToday = useCallback(() => {
+    event.emit({ type: 'scroll', date: today });
+  }, [event, start, today]);
+
+  return (
+    <div
+      {...composableProps(props, {
+        role: 'none',
+        classNames: ['shrink-0 grid! grid-cols-3 items-center bg-toolbar-surface', classNames],
+      })}
+      ref={forwardedRef}
+      style={{ width: defaultWidth }}
+    >
+      <div className='flex justify-start'>
+        <IconButton
+          variant='ghost'
+          icon='ph--calendar--regular'
+          iconOnly
+          classNames='aspect-square'
+          label={t('today.button')}
+          onClick={handleToday}
+        />
+      </div>
+      <div className='flex justify-center p-2 text-description'>{format(selected ?? top, 'MMMM')}</div>
+      <div className='flex justify-end p-2 text-description'>{(selected ?? top).getFullYear()}</div>
+    </div>
+  );
+});
+
+CalendarToolbar.displayName = CALENDAR_TOOLBAR_NAME;
+
+//
+// Grid
+// TODO(burdon): Key nav.
+// TODO(burdon): Drag range.
+//
+
+const CALENDAR_GRID_NAME = 'CalendarGrid';
+
+type CalendarGridProps = {
+  rows?: number;
+  /** Dates to highlight on the grid. Each date that appears in this array receives a border indicator. */
+  dates?: Date[];
+  onSelect?: (event: { date: Date }) => void;
+};
+
+const CalendarGrid = composable<HTMLDivElement, CalendarGridProps>(
+  ({ classNames, rows, dates = [], onSelect, ...props }, forwardedRef) => {
+    const { weekStartsOn, event, setIndex, selected, setSelected } = useCalendarContext(CALENDAR_GRID_NAME);
+    const { ref: containerRef, width = 0, height = 0 } = useResizeDetector();
+    const maxHeight = rows ? rows * size : undefined;
+    const listRef = useRef<List>(null);
+    const today = useMemo(() => new Date(), []);
+
+    // Build a set of ISO date strings (YYYY-MM-DD) for O(1) per-cell lookup.
+    const dateSet = useMemo(() => new Set(dates.map((date) => startOfDay(date).toISOString())), [dates]);
+
+    const hasDate = useCallback((date: Date) => dateSet.has(startOfDay(date).toISOString()), [dateSet]);
+
+    const [initialized, setInitialized] = useState(false);
+    useEffect(() => {
+      const index = differenceInWeeks(today, start);
+      listRef.current?.scrollToRow(index);
+    }, [initialized, start, today]);
+
+    useEffect(() => {
+      return event.on((event) => {
+        switch (event.type) {
+          case 'scroll': {
+            const index = differenceInWeeks(event.date, start);
+            listRef.current?.scrollToRow(index);
+            break;
+          }
+        }
+      });
+    }, [event]);
+
+    const days = useMemo(() => {
+      const weekStart = startOfWeek(new Date(), { weekStartsOn });
+      return Array.from({ length: 7 }, (_, i) => {
+        const day = addDays(weekStart, i);
+        return format(day, 'EEE'); // Short day name (Mon, Tue, etc.)
+      });
+    }, []);
+
+    // TODO(burdon): Get info by range.
+
+    const handleDaySelect = useCallback(
+      (date: Date) => {
+        setSelected((current) => (isSameDay(date, current) ? undefined : date));
+        onSelect?.({ date });
+      },
+      [onSelect],
+    );
+
+    const handleScroll = useCallback<NonNullable<ListProps['onScroll']>>((info) => {
+      setIndex(Math.round(info.scrollTop / size));
+    }, []);
+
+    const rowRenderer = useCallback<ListRowRenderer>(
+      ({ key, index, style }) => {
+        const getBgColor = (date: Date) => date.getMonth() % 2 === 0 && 'bg-modal-surface';
+        return (
+          <div key={key} style={style} className='grid'>
+            <div className='grid grid-cols-7 bg-input-surface' style={{ gridTemplateColumns: `repeat(7, ${size}px)` }}>
+              {Array.from({ length: 7 }).map((_, i) => {
+                const date = getDate(start, index, i, weekStartsOn);
+                const border = isSameDay(date, selected)
+                  ? 'border-primary-500'
+                  : isSameDay(date, today)
+                    ? 'border-amber-500'
+                    : hasDate(date)
+                      ? 'border-neutral-700 border-dashed'
+                      : undefined;
+
+                return (
+                  <div
+                    key={i}
+                    className={mx('relative flex justify-center items-center cursor-pointer', getBgColor(date))}
+                    onClick={() => handleDaySelect(date)}
+                  >
+                    <span className='text-description'>{date.getDate()}</span>
+                    {!border && date.getDate() === 1 && (
+                      <span className='absolute top-0 text-xs text-description'>{format(date, 'MMM')}</span>
+                    )}
+                    {border && <div className={mx('absolute inset-1 border-2 rounded-full', border)} />}
+                  </div>
+                );
+              })}
+            </div>
+          </div>
+        );
+      },
+      [handleDaySelect, hasDate, selected, weekStartsOn],
+    );
+
+    return (
+      <div
+        {...composableProps(props, {
+          role: 'none',
+          classNames: ['flex flex-col h-full w-full justify-center overflow-hidden', classNames],
+        })}
+        ref={forwardedRef}
+      >
+        {/* Day of week labels */}
+        <div className='grid w-full grid-cols-7' style={{ width: defaultWidth }}>
+          {days.map((date, i) => (
+            <div key={i} className='flex justify-center p-2 text-sm font-thin'>
+              {date}
+            </div>
+          ))}
+        </div>
+
+        {/* Grid */}
+        <div className='flex flex-col h-full w-full justify-center overflow-hidden' ref={containerRef}>
+          <List
+            ref={listRef}
+            role='none'
+            className='scrollbar-none outline-hidden'
+            width={width}
+            height={maxHeight ?? height}
+            rowCount={maxRows}
+            rowHeight={size}
+            rowRenderer={rowRenderer}
+            scrollToAlignment='start'
+            onScroll={handleScroll}
+            onRowsRendered={() => setInitialized(true)}
+          />
+        </div>
+      </div>
+    );
+  },
+);
+
+CalendarGrid.displayName = CALENDAR_GRID_NAME;
+
+//
+// Calendar
+//
+
+export const Calendar = {
+  Root: CalendarRoot,
+  Toolbar: CalendarToolbar,
+  Grid: CalendarGrid,
+};
+
+export type { CalendarController, CalendarRootProps, CalendarToolbarProps, CalendarGridProps };

package/src/components/Calendar/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './Calendar';

package/src/components/Calendar/util.ts

@@ -0,0 +1,22 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type Day } from 'date-fns';
+
+export const getDate = (start: Date, weekNumber: number, dayOfWeek: number, weekStartsOn: Day): Date => {
+  const result = new Date(start);
+  const startDayOfWeek = start.getDay(); // 0 = Sunday, 1 = Monday, etc.
+  const adjustedStartDay = (startDayOfWeek === 0 ? 7 : startDayOfWeek) - weekStartsOn; // Adjust for weekStartsOn.
+  result.setDate(start.getDate() - adjustedStartDay + weekNumber * 7 + dayOfWeek);
+  return result;
+};
+
+export const isSameDay = (date1: Date, date2: Date | undefined): boolean => {
+  return (
+    !!date2 &&
+    date1.getFullYear() === date2.getFullYear() &&
+    date1.getMonth() === date2.getMonth() &&
+    date1.getDate() === date2.getDate()
+  );
+};

package/src/components/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './Calendar';

package/src/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './components';

package/src/translations.ts

@@ -0,0 +1,17 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { type Resource } from '@dxos/react-ui';
+
+export const translationKey = '@dxos/react-ui-calendar';
+
+export const translations = [
+  {
+    'en-US': {
+      [translationKey]: {
+        'today.button': 'Today',
+      },
+    },
+  },
+] as const satisfies Resource[];

package/src/types.ts

@@ -0,0 +1,193 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type Locale } from 'date-fns';
+import { type RefObject } from 'react';
+
+/**
+ * Calendar types and interfaces.
+ */
+
+export type DateString = string; // YYYY-MM-DD format
+
+export type DisplayMode = 'days' | 'years';
+
+export type LayoutMode = 'portrait' | 'landscape';
+
+/**
+ * Locale configuration for the calendar.
+ */
+export interface CalendarLocale {
+  blank?: string;
+  headerFormat?: string;
+  todayLabel?: {
+    long: string;
+    short?: string;
+  };
+  weekdays?: string[];
+  weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
+  locale?: Locale; // date-fns locale
+}
+
+/**
+ * Theme configuration for the calendar.
+ */
+export interface CalendarTheme {
+  floatingNav?: {
+    background?: string;
+    chevron?: string;
+    color?: string;
+  };
+  headerColor?: string;
+  selectionColor?: string | ((date: DateString) => string);
+  textColor?: {
+    active?: string;
+    default?: string;
+  };
+  todayColor?: string;
+  weekdayColor?: string;
+  overlayColor?: string;
+}
+
+/**
+ * Display options for the calendar.
+ */
+export interface DisplayOptions {
+  hideYearsOnSelect?: boolean;
+  layout?: LayoutMode;
+  overscanMonthCount?: number;
+  shouldHeaderAnimate?: boolean;
+  showHeader?: boolean;
+  showMonthsForYears?: boolean;
+  showOverlay?: boolean;
+  showTodayHelper?: boolean;
+  showWeekdays?: boolean;
+  todayHelperRowOffset?: number;
+}
+
+/**
+ * Month data structure.
+ */
+export interface MonthData {
+  month: number;
+  year: number;
+}
+
+/**
+ * Month rendering data.
+ */
+export interface MonthRenderData {
+  date: Date;
+  rows: number[][];
+}
+
+/**
+ * Day props for rendering.
+ */
+export interface DayProps {
+  date: DateString;
+  day: number;
+  month: number;
+  year: number;
+  monthShort: string;
+  currentYear: number;
+  isDisabled: boolean;
+  isToday: boolean;
+  isSelected: boolean;
+  isHighlighted?: boolean;
+  onClick?: (date: Date) => void;
+  handlers?: Record<string, any>;
+  className?: string;
+}
+
+/**
+ * Calendar props.
+ */
+export interface CalendarProps {
+  autoFocus?: boolean;
+  className?: string;
+  disabledDates?: Date[];
+  disabledDays?: number[];
+  display?: DisplayMode;
+  displayOptions?: DisplayOptions;
+  height?: number;
+  keyboardSupport?: boolean;
+  locale?: CalendarLocale;
+  max?: Date;
+  maxDate?: Date;
+  min?: Date;
+  minDate?: Date;
+  onScroll?: (scrollTop: number, event?: Event) => void;
+  onScrollEnd?: (scrollTop: number) => void;
+  onSelect?: (date: Date) => void;
+  onHighlightedDateChange?: (date: Date) => void;
+  rowHeight?: number;
+  scrollDate?: Date;
+  selected?: Date | DateString;
+  tabIndex?: number;
+  theme?: CalendarTheme;
+  width?: number | string;
+}
+
+/**
+ * Month props.
+ */
+export interface MonthProps {
+  monthDate: Date;
+  rows: number[][];
+  rowHeight: number;
+  selected?: DateString;
+  disabledDates?: DateString[];
+  disabledDays?: number[];
+  minDate: Date;
+  maxDate: Date;
+  today: Date;
+  locale: Required<CalendarLocale>;
+  theme: Required<CalendarTheme>;
+  showOverlay?: boolean;
+  isScrolling?: boolean;
+  onDayClick?: (date: Date) => void;
+}
+
+/**
+ * Hook return types for headless implementation.
+ */
+export interface UseCalendarReturn {
+  containerProps: {
+    ref: RefObject<HTMLDivElement>;
+    tabIndex?: number;
+    className?: string;
+    'aria-label': string;
+  };
+  display: DisplayMode;
+  locale: Required<CalendarLocale>;
+  theme: Required<CalendarTheme>;
+  displayOptions: Required<DisplayOptions>;
+  months: MonthData[];
+  today: Date;
+  scrollToDate: (date: Date, offset?: number, shouldAnimate?: boolean) => void;
+  scrollTo: (offset: number) => void;
+  getCurrentOffset: () => number;
+  getDateOffset: (date: Date) => number;
+  setDisplay: (display: DisplayMode) => void;
+}
+
+export interface UseDayReturn {
+  dayProps: {
+    onClick: () => void;
+    'data-date': DateString;
+    className?: string;
+  };
+  isSelected: boolean;
+  isToday: boolean;
+  isDisabled: boolean;
+  isHighlighted: boolean;
+  selectionColor?: string;
+}
+
+export interface UseMonthReturn {
+  days: DayProps[];
+  monthLabel: string;
+  showOverlay: boolean;
+}