@dxos/react-ui-calendar 0.8.4-main.548089c

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@dxos/react-ui-calendar",
+  "version": "0.8.4-main.548089c",
+  "description": "A calendar component.",
+  "homepage": "https://dxos.org",
+  "bugs": "https://github.com/dxos/dxos/issues",
+  "license": "MIT",
+  "author": "DXOS.org",
+  "type": "module",
+  "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"
+    }
+  },
+  "types": "dist/types/src/index.d.ts",
+  "typesVersions": {
+    "*": {}
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "@preact-signals/safe-react": "^0.9.0",
+    "@preact/signals-core": "^1.12.1",
+    "@radix-ui/react-context": "1.1.1",
+    "date-fns": "^3.3.1",
+    "react-resize-detector": "^11.0.1",
+    "react-virtualized": "^9.22.6",
+    "react-window": "^2.2.3",
+    "@dxos/async": "0.8.4-main.548089c",
+    "@dxos/debug": "0.8.4-main.548089c",
+    "@dxos/log": "0.8.4-main.548089c",
+    "@dxos/invariant": "0.8.4-main.548089c",
+    "@dxos/util": "0.8.4-main.548089c"
+  },
+  "devDependencies": {
+    "@types/react": "~19.2.2",
+    "@types/react-dom": "~19.2.2",
+    "@types/react-virtualized": "^9.22.3",
+    "@types/react-window": "^2.0.0",
+    "effect": "3.18.3",
+    "react": "~19.2.0",
+    "react-dom": "~19.2.0",
+    "vite": "7.1.9",
+    "@dxos/random": "0.8.4-main.548089c",
+    "@dxos/react-ui": "0.8.4-main.548089c",
+    "@dxos/react-ui-theme": "0.8.4-main.548089c",
+    "@dxos/storybook-utils": "0.8.4-main.548089c"
+  },
+  "peerDependencies": {
+    "effect": "3.13.3",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "@dxos/react-ui": "0.8.4-main.548089c",
+    "@dxos/react-ui-theme": "0.8.4-main.548089c"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

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

@@ -0,0 +1,76 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import React from 'react';
+
+import { 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,
+  decorators: [withTheme],
+  parameters: {
+    layout: 'centered',
+    translations,
+  },
+} satisfies Meta<typeof Calendar.Grid>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  render: () => (
+    <Calendar.Root>
+      <Calendar.Viewport>
+        <Calendar.Header />
+        <Calendar.Grid rows={6} />
+      </Calendar.Viewport>
+    </Calendar.Root>
+  ),
+};
+
+export const Border: Story = {
+  render: () => (
+    <Calendar.Root>
+      <Calendar.Viewport classNames='bg-modalSurface border border-separator rounded'>
+        <Calendar.Header />
+        <Calendar.Grid rows={6} />
+      </Calendar.Viewport>
+    </Calendar.Root>
+  ),
+};
+
+export const Column: Story = {
+  render: () => (
+    <div className='absolute inset-0 flex bs-full justify-center'>
+      <Calendar.Root>
+        <Calendar.Viewport>
+          <Calendar.Header />
+          <Calendar.Grid />
+        </Calendar.Viewport>
+      </Calendar.Root>
+    </div>
+  ),
+};
+
+export const Mobile: Story = {
+  render: () => (
+    <div className='absolute inset-0 flex bs-full justify-center'>
+      <div className='flex bs-full is-[400px] justify-center'>
+        <Calendar.Root>
+          <Calendar.Viewport classNames='is-full'>
+            <Calendar.Header />
+            <Calendar.Grid />
+          </Calendar.Viewport>
+        </Calendar.Root>
+      </div>
+    </div>
+  ),
+};

package/src/components/Calendar/Calendar.tsx

@@ -0,0 +1,294 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { createContext } from '@radix-ui/react-context';
+import { type Day, addDays, differenceInWeeks, format, 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, type ThemedClassName, useTranslation } from '@dxos/react-ui';
+import { mx } from '@dxos/react-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>
+    );
+  },
+);
+
+//
+// Viewport
+//
+
+type CalendarViewportProps = PropsWithChildren<ThemedClassName>;
+
+const CalendarViewport = ({ children, classNames }: CalendarViewportProps) => {
+  return (
+    <div role='none' className={mx('flex flex-col items-center overflow-hidden bg-inputSurface', classNames)}>
+      {children}
+    </div>
+  );
+};
+
+CalendarViewport.displayName = 'CalendarContent';
+
+//
+// Header
+//
+
+type CalendarHeaderProps = ThemedClassName;
+
+const CalendarHeader = ({ classNames }: CalendarHeaderProps) => {
+  const { t } = useTranslation(translationKey);
+  const { weekStartsOn, event, index, selected } = useCalendarContext(CalendarHeader.displayName);
+  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 role='none' className={mx('shink-0 is-full grid grid-cols-3', classNames)} style={{ width: defaultWidth }}>
+      <div className='flex justify-start'>
+        <IconButton
+          variant='ghost'
+          size={6}
+          icon='ph--calendar--regular'
+          iconOnly
+          classNames='aspect-square'
+          label={t('today button')}
+          onClick={handleToday}
+        />
+      </div>
+      <span className='flex justify-center p-2'>{format(selected ?? top, 'MMMM')}</span>
+      <span className='flex justify-end p-2'>{(selected ?? top).getFullYear()}</span>
+    </div>
+  );
+};
+
+CalendarHeader.displayName = 'CalendarHeader';
+
+//
+// Grid
+// TODO(burdon): Key nav.
+// TODO(burdon): Drag range.
+//
+
+type CalendarGridProps = ThemedClassName<{
+  rows?: number;
+  onSelect?: (event: { date: Date }) => void;
+}>;
+
+const CalendarGrid = ({ classNames, rows, onSelect }: CalendarGridProps) => {
+  const { weekStartsOn, event, setIndex, selected, setSelected } = useCalendarContext(CalendarGrid.displayName);
+  const { ref: containerRef, width = 0, height = 0 } = useResizeDetector();
+  const maxHeight = rows ? rows * size : undefined;
+  const listRef = useRef<List>(null);
+  const today = useMemo(() => new Date(), []);
+
+  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.)
+    });
+  }, []);
+
+  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-modalSurface';
+      return (
+        <div key={key} style={style} className='is-full grid grid-cols-[1fr_max-content_1fr] snap-center'>
+          <div className={mx(getBgColor(getDate(start, index, 0, weekStartsOn)))} />
+          <div className='grid grid-cols-7' 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'
+                  : 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 top-0 left-0 is-full bs-full border-2 rounded-full', border)} />
+                  )}
+                </div>
+              );
+            })}
+          </div>
+          <div className={mx(getBgColor(getDate(start, index, 6, weekStartsOn)))} />
+        </div>
+      );
+    },
+    [handleDaySelect, selected, weekStartsOn],
+  );
+
+  return (
+    <div role='none' className={mx('flex flex-col bs-full is-full justify-center overflow-hidden', classNames)}>
+      {/* Day labels */}
+      <div role='none' className='flex justify-center bg-groupSurface'>
+        <div role='none' className='flex is-full grid grid-cols-7' style={{ width: defaultWidth }}>
+          {days.map((date, i) => (
+            <div key={i} role='none' className='flex justify-center p-2 text-sm font-thin'>
+              {date}
+            </div>
+          ))}
+        </div>
+      </div>
+      {/* Grid */}
+      <div role='none' className='flex flex-col bs-full is-full justify-center overflow-hidden' ref={containerRef}>
+        <List
+          ref={listRef}
+          role='none'
+          // TODO(burdon): Snap isn't working.
+          className='[&>div]:snap-y scrollbar-none outline-none'
+          width={width}
+          height={maxHeight ?? height}
+          rowCount={maxRows}
+          rowHeight={size}
+          rowRenderer={rowRenderer}
+          scrollToAlignment='start'
+          onScroll={handleScroll}
+          onRowsRendered={() => setInitialized(true)}
+        />
+      </div>
+    </div>
+  );
+};
+
+CalendarGrid.displayName = 'CalendarGrid';
+
+//
+// Calendar
+//
+
+export const Calendar = {
+  Root: CalendarRoot,
+  Viewport: CalendarViewport,
+  Header: CalendarHeader,
+  Grid: CalendarGrid,
+};
+
+export type { CalendarController, CalendarRootProps, CalendarViewportProps, CalendarHeaderProps, 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 = '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;
+}