fix-issues/4725: exported fromDate & fromEpoch and fixed the documentation (#4732)

* fix-issues/4725: exported fromDate &  fromEpoch and fixed the documentations

* Comment fix: using fromAbsolute and updated docs

* Update packages/@internationalized/date/docs/ZonedDateTime.mdx

Thanks. Indeed this is more intuitive now

Co-authored-by: Daniel Lu <[email protected]>

* Update packages/@internationalized/date/src/conversion.ts

Co-authored-by: Robert Snow <[email protected]>

* Update packages/@internationalized/date/src/conversion.ts

Co-authored-by: Robert Snow <[email protected]>

* Update packages/@internationalized/date/docs/ZonedDateTime.mdx

Co-authored-by: Robert Snow <[email protected]>

* Update packages/@internationalized/date/docs/ZonedDateTime.mdx

Co-authored-by: Robert Snow <[email protected]>

---------

Co-authored-by: Naveen Kumar <[email protected]>
Co-authored-by: Daniel Lu <[email protected]>
Co-authored-by: Robert Snow <[email protected]>

Author: 4 people

packages/@internationalized/date/docs/ZonedDateTime.mdx

@@ -61,6 +61,19 @@ let date = parseAbsolute('2021-11-07T07:45:00Z', 'America/Los_Angeles');
 let date = parseAbsoluteToLocal('2021-11-07T07:45:00Z');
 ```
 
+You can also create a `ZonedDateTime` using a `Date` object or epoch time (milliseconds) using one of the following functions:
+
+* <TypeLink links={docs.links} type={docs.exports.fromDate} /> – This function creates a `ZonedDateTime` from a `Date` object. A time zone identifier, e.g. `America/Los_Angeles`, must be passed, and the result will be converted into that time zone.
+* <TypeLink links={docs.links} type={docs.exports.fromAbsolute} /> – This function creates a `ZonedDateTime` from a Unix epoch (e.g. `1688023843144`, representing milliseconds since 1970). A time zone identifier, e.g. `America/Los_Angeles`, must be provided, and the result will be converted into that time zone.
+
+```tsx
+import {fromDate, fromAbsolute} from '@internationalized/date';
+
+let date = fromDate(new Date(), 'America/Los_Angeles');
+let date = fromAbsolute(1688023843144, 'America/Los_Angeles');
+```
+
+
 The current time can be retrieved using the <TypeLink links={docs.links} type={docs.exports.now} /> function. This requires a time zone identifier to be provided, which is used to determine the local time. The <TypeLink links={docs.links} type={docs.exports.getLocalTimeZone} /> function can be used to retrieve the user's current time zone.
 
 ```tsx

packages/@internationalized/date/src/conversion.ts

@@ -173,6 +173,9 @@ export function toDate(dateTime: CalendarDate | CalendarDateTime, timeZone: stri
   return new Date(toAbsolute(dateTime, timeZone, disambiguation));
 }
 
+/**
+ * Takes a Unix epoch (milliseconds since 1970) and converts it to the provided time zone.
+ */
 export function fromAbsolute(ms: number, timeZone: string): ZonedDateTime {
   let offset = getTimeZoneOffset(ms, timeZone);
   let date = new Date(ms + offset);
@@ -187,6 +190,9 @@ export function fromAbsolute(ms: number, timeZone: string): ZonedDateTime {
   return new ZonedDateTime(year, month, day, timeZone, offset, hour, minute, second, millisecond);
 }
 
+/**
+ * Takes a `Date` object and converts it to the provided time zone.
+ */
 export function fromDate(date: Date, timeZone: string): ZonedDateTime {
   return fromAbsolute(date.getTime(), timeZone);
 }

packages/@internationalized/date/src/index.ts

@@ -38,7 +38,17 @@ export {IslamicCivilCalendar, IslamicTabularCalendar, IslamicUmalquraCalendar} f
 export {HebrewCalendar} from './calendars/HebrewCalendar';
 export {EthiopicCalendar, EthiopicAmeteAlemCalendar, CopticCalendar} from './calendars/EthiopicCalendar';
 export {createCalendar} from './createCalendar';
-export {toCalendarDate, toCalendarDateTime, toTime, toCalendar, toZoned, toTimeZone, toLocalTimeZone} from './conversion';
+export {
+  toCalendarDate,
+  toCalendarDateTime,
+  toTime,
+  toCalendar,
+  toZoned,
+  toTimeZone,
+  toLocalTimeZone,
+  fromDate,
+  fromAbsolute
+} from './conversion';
 export {
   isSameDay,
   isSameMonth,