+
+
+ 
+
+ 
+
+ 
+
+ 
+
+ 
+
+ 
+
+ 
+
+
+Enjoy this library? Try the entire [TanStack](https://tanstack.com)!
+
+## Visit [tanstack.com/time](https://tanstack.com/time) for docs, guides, API and more!
diff --git a/adr/choosing-a-date-time-handling-solution.md b/adr/choosing-a-date-time-handling-solution.md
new file mode 100644
index 00000000..03aae494
--- /dev/null
+++ b/adr/choosing-a-date-time-handling-solution.md
@@ -0,0 +1,91 @@
+# ADR: Choosing a Date and Time Handling Solution
+
+## Status
+
+Accepted, decided on Temporal API.
+
+## Context
+
+In modern web applications, accurate and efficient handling of dates and times is crucial. Traditional JavaScript `Date`` objects have several limitations and pitfalls, including:
+- Lack of support for different calendars
+- Difficulties with time zone conversions
+- Ambiguous and error-prone APIs for date and time manipulation
+
+These issues often lead to bugs and inefficiencies in handling date and time data, especially in complex applications that require extensive date and time manipulations, such as calendar applications.
+
+## Decision
+
+After evaluating several options, we have decided to adopt the Temporal API for all date and time handling in our application. Temporal is a new standard for working with dates and times in JavaScript, designed to provide a more reliable, readable, and easy-to-use API.
+
+### Evaluation of Alternatives
+
+1. **JavaScript `Date`**
+ - **Pros**:
+ - Built-in and requires no additional dependencies.
+ - Supported natively in all JavaScript environments.
+ - **Cons**:
+ - Ambiguous and error-prone API.
+ - Poor support for time zones and different calendars.
+ - Mutable objects, leading to potential bugs.
+ - Date arithmetic is complex and error-prone.
+
+2. **moment.js**
+ - **Pros**:
+ - Widely used and battle-tested.
+ - Rich feature set for date manipulation and formatting.
+ - **Cons**:
+ - Large library size, affecting bundle size.
+ - Mutable objects, leading to potential bugs.
+ - Moment.js is in maintenance mode, with no new features planned.
+
+3. **date-fns**
+ - **Pros**:
+ - Modular approach, allowing selective imports to reduce bundle size.
+ - Immutable and functional API.
+ - Good support for date arithmetic and formatting.
+ - **Cons**:
+ - Limited support for time zones without additional libraries.
+ - Requires combining multiple functions for complex operations.
+
+### Reasons for Choosing Temporal
+
+1. **Clarity and Readability**: Temporal's API is designed to be intuitive and readable. For example, creating a date in Temporal is straightforward and unambiguous:
+ ```javascript
+ const date = Temporal.PlainDate.from('2024-06-01');
+ ```
+ This is much clearer than the equivalent using `Date`:
+ ```javascript
+ const date = new Date('2024-06-01');
+ ```
+
+2. **Immutability**: Temporal objects are immutable, meaning that once created, they cannot be changed. This immutability prevents common bugs related to date manipulation and makes the code easier to reason about.
+
+3. **Comprehensive Support for Calendars and Time Zones**: Temporal natively supports different calendars and time zones, making it ideal for applications that need to handle internationalization and localization.
+
+4. **Precise Arithmetic Operations**: Temporal provides precise and easy-to-use methods for date and time arithmetic, avoiding the pitfalls of JavaScript `Date` arithmetic:
+ ```javascript
+ const nextMonth = date.add({ months: 1 });
+ ```
+
+5. **Better Error Handling**: Temporal's API is designed to throw errors for invalid operations, which helps in catching bugs early in the development process.
+
+6. **Standardization**: Temporal is an upcoming standard for date and time handling in JavaScript, which means it will have long-term support and improvements from the community and browser vendors.
+
+## Consequences
+
+### Positive
+
+- **Reduced Bugs**: By using Temporal, we expect to see a reduction in date and time-related bugs, especially those related to time zone conversions and date arithmetic.
+- **Improved Code Quality**: The clarity and immutability of Temporal will lead to more readable and maintainable code.
+- **Enhanced Features**: Support for multiple calendars and time zones will allow us to build more robust and feature-rich internationalized applications.
+
+### Negative
+
+- **Learning Curve**: Developers will need to learn the new Temporal API, which might slow down initial development.
+- **Polyfill Requirement**: Until Temporal is fully supported in all target environments, we will need to include a polyfill, which may slightly increase the bundle size.
+
+## Conclusion
+
+After evaluating various options for date and time handling in JavaScript, we have decided to adopt the Temporal API. Temporal provides a robust, readable, and reliable API that addresses the shortcomings of the existing `Date` object and offers comprehensive support for internationalization and time zone handling. Despite the initial learning curve and the need for a polyfill, the long-term benefits make Temporal the best choice for our application's needs.
+
+By documenting this decision, we ensure that future developers understand the rationale behind adopting Temporal and can build upon this foundation with confidence.
diff --git a/docs/framework/react/reference/useCalendar.md b/docs/framework/react/reference/useCalendar.md
new file mode 100644
index 00000000..fbc0ffa5
--- /dev/null
+++ b/docs/framework/react/reference/useCalendar.md
@@ -0,0 +1,227 @@
+---
+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.
+- `resources?: TResource[] | null`
+Optional resources to be used in the calendar.
+- `range?: DateRange`
+Optional range of dates to be used in the calendar.
+
+### 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: string) => void`
+This function navigates to a specific period based on the provided date.
+- `days: Day| + {month[0]?.date.toLocaleString('default', { month: 'long' })}{' '} + {month[0]?.date.year} + | +
|---|
| + {dayName} + | + ))} +
|
+ {day.date.day}
+
+ {day.events.map((event) => (
+
+
+ {event.title}
+
+ ))}
+ |
+ ))}
+
| + {dayName} + | + ))} +
|
+ {day.date.day}
+
+ {day.events.map((event) => (
+
+
+ {event.title}
+
+ ))}
+ |
+ ))}
+
| + {dayName} + | + ))} +
|
+ {day.date.day}
+
+ {day.events.map((event) => (
+
+
+ {event.title}
+
+ ))}
+ |
+ ))}
+
No dates selected
+ )} +