feat: calendar core

docs/framework/react/reference/useCalendar.md

@@ -0,0 +1,223 @@
+---
+title: Use Calendar
+id: useCalendar
+---
+
+### `useCalendar`
+
+```tsx
+export function useCalendar({
+  weekStartsOn,
+  events,
+  viewMode,
+  locale,
+  onChangeViewMode,
+}: UseCalendarProps)
+```
+
+`useCalendar` is a hook that provides a comprehensive set of functionalities for managing calendar events, view modes, and period navigation.
+
+
+#### Parameters
+
+- `events?: TEvent[] | null`
+An optional array of events to be handled by the calendar.
+- `viewMode: CalendarStore['viewMode']`
+The initial view mode configuration of the calendar.
+- `locale?: Intl.UnicodeBCP47LocaleIdentifier`
+Optional locale for date formatting. Uses a BCP 47 language tag.
+- `timeZone?: Temporal.TimeZoneLike`
+Optional time zone specification for the calendar.
+- `calendar?: Temporal.CalendarLike`
+Optional calendar system to be used.
+
+
+#### Returns
+
+`firstDayOfPeriod: Temporal.PlainDate`
+This value represents the first day of the current period displayed by the calendar.
+`currentPeriod: string`
+This value represents a string that describes the current period displayed by the calendar.
+`goToPreviousPeriod: () => void`
+This function navigates to the previous period.
+`goToNextPeriod: () => void`
+This function navigates to the next period.
+- `goToCurrentPeriod: () => void`
+This function navigates to the current period.
+- `goToSpecificPeriod: (date: Temporal.PlainDate) => void`
+This function navigates to a specific period based on the provided date.
+- `days: Day[]`
+This value represents an array of days in the current period displayed by the calendar.
+- `daysNames: string[]`
+This value represents an array of strings that contain the names of the days of the week.
+- `viewMode: CalendarStore['viewMode']`
+This value represents the current view mode of the calendar.
+- `changeViewMode: (newViewMode: CalendarStore['viewMode']) => void`
+This function is used to change the view mode of the calendar.
+- `getEventProps: (id: string) => { style: CSSProperties } | null`
+This function is used to retrieve the style properties for a specific event based on its ID.
+- `getCurrentTimeMarkerProps: () => { style: CSSProperties, currentTime: string | undefined }`
+This function is used to retrieve the style properties and current time for the current time marker.
+- `isPending: boolean`
+This value represents whether the calendar is in a pending state.
+- `groupDaysBy: (props: Omit<GroupDaysByProps<TEvent>, 'weekStartsOn'>) => (Day<TEvent> | null)[][]`
+This function is used to group the days in the current period by a specified unit. The fillMissingDays parameter can be used to fill in missing days with previous or next month's days.
+
+#### Example Usage
+
+```tsx
+const CalendarComponent = ({ events }) => {
+  const {
+    firstDayOfPeriod,
+    currentPeriod,
+    goToPreviousPeriod,
+    goToNextPeriod,
+    goToCurrentPeriod,
+    goToSpecificPeriod,
+    changeViewMode,
+    days,
+    daysNames,
+    viewMode,
+    getEventProps,
+    getCurrentTimeMarkerProps,
+    groupDaysBy,
+  } = useCalendar({
+    viewMode: { value: 1, unit: 'month' },
+    events,
+    locale: 'en-US',
+    timeZone: 'America/New_York',
+    calendar: 'gregory',
+  });
+
+  return (
+    <div className="calendar-container">
+      <div className="calendar-header">
+        <button onClick={goToPreviousPeriod}>Previous</button>
+        <button onClick={goToCurrentPeriod}>Today</button>
+        <button onClick={goToNextPeriod}>Next</button>
+      </div>
+      <div className="calendar-view-mode">
+        <button onClick={() => changeViewMode({ value: 1, unit: 'month' })}>Month View</button>
+        <button onClick={() => changeViewMode({ value: 1, unit: 'week' })}>Week View</button>
+        <button onClick={() => changeViewMode({ value: 3, unit: 'day' })}>3-Day View</button>
+        <button onClick={() => changeViewMode({ value: 1, unit: 'day' })}>1-Day View</button>
+      </div>
+      <table className="calendar-table">
+        {viewMode.unit === 'month' && (
+          groupDaysBy(days, 'months').map((month, monthIndex) => (
+            <tbody key={monthIndex} className="calendar-month">
+              <tr>
+                <th colSpan={7} className="calendar-month-name">
+                  {month[0]?.date.toLocaleString('default', { month: 'long' })}{' '}
+                  {month[0]?.date.year}
+                </th>
+              </tr>
+              <tr>
+                {daysNames.map((dayName, index) => (
+                  <th key={index} className="calendar-day-name">
+                    {dayName}
+                  </th>
+                ))}
+              </tr>
+              {groupDaysBy(month, 'weeks').map((week, weekIndex) => (
+                <tr key={weekIndex} className="calendar-week">
+                  {week.map((day) => (
+                    <td
+                      key={day.date.toString()}
+                      className={`calendar-day ${day.isToday ? 'today' : ''
+                        } ${day.isInCurrentPeriod ? 'current' : 'not-current'}`}
+                    >
+                      <div className="calendar-date">{day.date.day}</div>
+                      <div className="calendar-events">
+                        {day.events.map((event) => (
+                          <div
+                            key={event.id}
+                            className="calendar-event"
+                            style={getEventProps(event.id)?.style}
+                          >
+                            {event.title}
+                          </div>
+                        ))}
+                      </div>
+                    </td>
+                  ))}
+                </tr>
+              ))}
+            </tbody>
+          ))
+        )}
+
+        {viewMode.unit === 'week' && (
+          <tbody className="calendar-week">
+            <tr>
+              {daysNames.map((dayName, index) => (
+                <th key={index} className="calendar-day-name">
+                  {dayName}
+                </th>
+              ))}
+            </tr>
+            {groupDaysBy(days, 'weeks').map((week, weekIndex) => (
+              <tr key={weekIndex}>
+                {week.map((day) => (
+                  <td
+                    key={day.date.toString()}
+                    className={`calendar-day ${day.isToday ? 'today' : ''
+                      } ${day.isInCurrentPeriod ? 'current' : 'not-current'}`}
+                  >
+                    <div className="calendar-date">{day.date.day}</div>
+                    <div className="calendar-events">
+                      {day.events.map((event) => (
+                        <div
+                          key={event.id}
+                          className="calendar-event"
+                          style={getEventProps(event.id)?.style}
+                        >
+                          {event.title}
+                        </div>
+                      ))}
+                    </div>
+                  </td>
+                ))}
+              </tr>
+            ))}
+          </tbody>
+        )}
+
+        {viewMode.unit === 'day' && (
+          <tbody className="calendar-day">
+            <tr>
+              {daysNames.map((dayName, index) => (
+                <th key={index} className="calendar-day-name">
+                  {dayName}
+                </th>
+              ))}
+            </tr>
+            <tr>
+              {days.map((day) => (
+                <td
+                  key={day.date.toString()}
+                  className={`calendar-day ${day.isToday ? 'today' : ''
+                    } ${day.isInCurrentPeriod ? 'current' : 'not-current'}`}
+                >
+                  <div className="calendar-date">{day.date.day}</div>
+                  <div className="calendar-events">
+                    {day.events.map((event) => (
+                      <div
+                        key={event.id}
+                        className="calendar-event"
+                        style={getEventProps(event.id)?.style}
+                      >
+                        {event.title}
+                      </div>
+                    ))}
+                  </div>
+                </td>
+              ))}
+            </tr>
+          </tbody>
+        )}
+      </table>
+    </div>
+  );
+};
+```

docs/reference/calendar-core.md

@@ -0,0 +1,118 @@
+---
+title: Calendar Core
+id: calendar-core
+---
+
+### `CalendarCore`
+
+```tsx
+export class CalendarCore<TEvent extends Event> {
+  constructor(options: CalendarCoreOptions<TEvent>);
+}
+```
+
+The `CalendarCore` class provides a set of functionalities for managing calendar events, view modes, and period navigation. This class is designed to be used in various calendar applications where precise date management and event handling are required.
+
+
+#### Parameters
+
+- `weekStartsOn?: number`
+An optional number that specifies the day of the week that the calendar should start on. It defaults to 1 (Monday).
+- `events?: TEvent[]`
+An optional array of events that the calendar should display.
+- `viewMode: ViewMode`
+An object that specifies the initial view mode of the calendar.
+- `locale?: Parameters<Temporal.PlainDate['toLocaleString']>['0']`
+An optional string that specifies the locale to use for formatting dates and times.
+- `timeZone?: Temporal.TimeZoneLike`
+Optional time zone specification for the calendar.
+- `calendar?: Temporal.CalendarLike`
+Optional calendar system to be used.
+
+
+#### Returns
+
+- `getDaysWithEvents(): Array<Day<TEvent>>`
+Returns an array of days in the current period with their associated events.
+- `getDaysNames(): string[]`
+Returns an array of strings representing the names of the days of the week based on the locale and week start day.
+- `changeViewMode(newViewMode: CalendarStore['viewMode']): void`
+Changes the view mode of the calendar.
+- `goToPreviousPeriod(): void`
+Navigates to the previous period based on the current view mode.
+- `goToNextPeriod(): void`
+Navigates to the next period based on the current view mode.
+- `goToCurrentPeriod(): void`
+Navigates to the current period.
+- `goToSpecificPeriod(date: Temporal.PlainDate): void`
+Navigates to a specific period based on the provided date.
+- `updateCurrentTime(): void`
+Updates the current time.
+- `getEventProps(id: Event['id']): { style: CSSProperties } | null`
+Retrieves the style properties for a specific event based on its ID.
+- `getCurrentTimeMarkerProps(): { style: CSSProperties; currentTime: string | undefined }`
+Retrieves the style properties and current time for the current time marker.
+- `groupDaysBy(props: Omit<GroupDaysByProps<TEvent>, 'weekStartsOn'>): (Day<TEvent> | null)[][]`
+Groups the days in the current period by a specified unit. The fillMissingDays parameter can be used to fill in missing days with previous or next month's days.
+
+
+#### Example Usage
+
+```ts
+import { CalendarCore, Event } from '@tanstack/time';
+import { Temporal } from '@js-temporal/polyfill';
+
+interface MyEvent extends Event {
+  location: string;
+}
+
+const events: MyEvent[] = [
+  {
+    id: '1',
+    startDate: Temporal.PlainDateTime.from('2024-06-10T09:00'),
+    endDate: Temporal.PlainDateTime.from('2024-06-10T10:00'),
+    title: 'Event 1',
+    location: 'Room 101',
+  },
+  {
+    id: '2',
+    startDate: Temporal.PlainDateTime.from('2024-06-12T11:00'),
+    endDate: Temporal.PlainDateTime.from('2024-06-12T12:00'),
+    title: 'Event 2',
+    location: 'Room 202',
+  },
+];
+
+const calendarCore = new CalendarCore<MyEvent>({
+  viewMode: { value: 1, unit: 'month' },
+  events,
+  locale: 'en-US',
+  timeZone: 'America/New_York',
+  calendar: 'gregory',
+});
+
+// Get days with events
+const daysWithEvents = calendarCore.getDaysWithEvents();
+console.log(daysWithEvents);
+
+// Change view mode to week
+calendarCore.changeViewMode({ value: 1, unit: 'week' });
+
+// Navigate to the next period
+calendarCore.goToNextPeriod();
+
+// Update current time
+calendarCore.updateCurrentTime();
+
+// Get event properties
+const eventProps = calendarCore.getEventProps('1');
+console.log(eventProps);
+
+// Get current time marker properties
+const currentTimeMarkerProps = calendarCore.getCurrentTimeMarkerProps();
+console.log(currentTimeMarkerProps);
+
+// Group days by week
+const groupedDays = calendarCore.groupDaysBy({ days: daysWithEvents, unit: 'week' });
+console.log(groupedDays);
+```

packages/react-time/package.json

@@ -62,7 +62,10 @@
     "react-dom": "^17.0.0 || ^18.0.0"
   },
   "dependencies": {
+    "@js-temporal/polyfill": "^0.4.4",
+    "@tanstack/react-store": "^0.4.1",
     "@tanstack/time": "workspace:*",
+    "typesafe-actions": "^5.1.0",
     "use-sync-external-store": "^1.2.0"
   },
   "devDependencies": {

packages/react-time/src/index.ts

@@ -1,3 +1 @@
-/**
- *  TanStack Time
- */
+export { useCalendar } from './useCalendar';