[new-ci] Reference for stage 3 temporal #37344

Josh-Cena · 2024-12-23T06:12:53Z

~~Far from ready for review, and I'll work on this alone for a while~~

It is now ready for review! It's extremely big but I think it's more worthwhile getting it in as a whole. I`m already leaving the guide to a second PR.

For reviewers (both editorial and technical): I've made a spreadsheet here: https://docs.google.com/spreadsheets/d/1RrRHL0m08R4V4WtuWBbSWr9a1gO4RiIaH42WrPv_Uhs/edit Welcoming anyone on the team for editorial reviews! Technical review from the champion group is greatly appreciated too. It seems we have roughly 4 weeks to make this happen.

github-actions · 2024-12-23T06:15:11Z

Preview URLs (282 pages)

External URLs (41)

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON
Title: JSON

https://datatracker.ietf.org/doc/html/rfc8259 (1 time)
https://en.wikipedia.org/wiki/Augmented_Backus%E2%80%93Naur_form (1 time)
https://en.wikipedia.org/wiki/YAML (1 time)
https://github.com/tc39/proposal-json-superset (1 time)
https://json-diff.com/ (1 time)
https://json.org/ (1 time)
https://json5.org/ (1 time)
https://jsonbeautifier.org/ (1 time)
https://jsonparser.org/ (1 time)
https://tools.learningcontainer.com/json-validator/ (1 time)

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal
Title: Temporal

https://datatracker.ietf.org/doc/html/rfc3339 (1 time) (Note! This may be a new URL 👀)
https://datatracker.ietf.org/doc/html/rfc9557 (1 time) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainDate
Title: Temporal.PlainDate

https://datatracker.ietf.org/doc/html/rfc3339 (1 time) (Note! This may be a new URL 👀)
https://datatracker.ietf.org/doc/html/rfc9557 (1 time) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainDate/day
Title: Temporal.PlainDate.prototype.day

https://en.wikipedia.org/wiki/Adoption_of_the_Gregorian_calendar (1 time) (Note! This may be a new URL 👀)
https://en.wikipedia.org/wiki/Proleptic_Gregorian_calendar (1 time) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Instant
Title: Temporal.Instant

https://datatracker.ietf.org/doc/html/rfc3339 (1 time) (Note! This may be a new URL 👀)
https://datatracker.ietf.org/doc/html/rfc9557 (1 time) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainYearMonth
Title: Temporal.PlainYearMonth

https://datatracker.ietf.org/doc/html/rfc3339 (1 time) (Note! This may be a new URL 👀)
https://datatracker.ietf.org/doc/html/rfc9557 (1 time) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/ZonedDateTime
Title: Temporal.ZonedDateTime

https://datatracker.ietf.org/doc/html/rfc3339 (1 time) (Note! This may be a new URL 👀)
https://datatracker.ietf.org/doc/html/rfc9557 (1 time) (Note! This may be a new URL 👀)
https://github.com/unicode-org/cldr-json/blob/main/cldr-json/cldr-bcp47/bcp47/timezone.json (2 times) (Note! This may be a new URL 👀)
https://unicode.org/reports/tr35/ (1 time) (Note! This may be a new URL 👀)
https://www.iana.org/time-zones (1 time) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/ZonedDateTime/day
Title: Temporal.ZonedDateTime.prototype.day

https://en.wikipedia.org/wiki/Time_in_Samoa (1 time) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/ZonedDateTime/add
Title: Temporal.ZonedDateTime.prototype.add()

https://datatracker.ietf.org/doc/html/rfc5545 (1 time) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/ZonedDateTime/since
Title: Temporal.ZonedDateTime.prototype.since()

https://datatracker.ietf.org/doc/html/rfc5545 (1 time) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainDateTime
Title: Temporal.PlainDateTime

https://datatracker.ietf.org/doc/html/rfc3339 (1 time) (Note! This may be a new URL 👀)
https://datatracker.ietf.org/doc/html/rfc9557 (1 time) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainMonthDay
Title: Temporal.PlainMonthDay

https://datatracker.ietf.org/doc/html/rfc3339 (1 time) (Note! This may be a new URL 👀)
https://datatracker.ietf.org/doc/html/rfc9557 (1 time) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Duration
Title: Temporal.Duration

<https://en.wikipedi…

TRUNCATED!

bsmth

For Temporal.Now

files/en-us/web/javascript/reference/global_objects/temporal/now/index.md

files/en-us/web/javascript/reference/global_objects/temporal/now/timezoneid/index.md

meyerweb

PlainTime, PlainYearMonth, and ZonedDateTime indexes

files/en-us/web/javascript/reference/global_objects/temporal/plaintime/index.md

files/en-us/web/javascript/reference/global_objects/temporal/plainyearmonth/index.md

files/en-us/web/javascript/reference/global_objects/temporal/zoneddatetime/index.md

files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/index.md

meyerweb

Temporal index page

files/en-us/web/javascript/reference/global_objects/temporal/index.md

Co-authored-by: Eric A. Meyer <[email protected]>

chrisdavidmills

Giving my approval, so I don't end up blocking this one later on.

bsmth

One comment for Time zone & calendar group

files/en-us/web/javascript/reference/global_objects/temporal/zoneddatetime/timezoneid/index.md

bsmth

One comment for Time components group

files/en-us/web/javascript/reference/global_objects/temporal/zoneddatetime/minute/index.md

meyerweb

Temporal.Instant constructors

files/en-us/web/javascript/reference/global_objects/temporal/instant/instant/index.md

...en-us/web/javascript/reference/global_objects/temporal/instant/fromepochnanoseconds/index.md

...n-us/web/javascript/reference/global_objects/temporal/instant/fromepochmilliseconds/index.md

meyerweb

Temporal.PlainDate constructors

files/en-us/web/javascript/reference/global_objects/temporal/plaindate/plaindate/index.md

files/en-us/web/javascript/reference/global_objects/temporal/plaindate/from/index.md

files/en-us/web/javascript/reference/global_objects/temporal/plaindate/with/index.md

meyerweb

Temporal.PlainDateTime and Temporal.PlainTime constructors

files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/from/index.md

files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/with/index.md

bsmth

Few comments for Arithmetic group

files/en-us/web/javascript/reference/global_objects/temporal/instant/subtract/index.md

files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/since/index.md

files/en-us/web/javascript/reference/global_objects/temporal/plaindate/until/index.md

files/en-us/web/javascript/reference/global_objects/temporal/plaintime/since/index.md

files/en-us/web/javascript/reference/global_objects/temporal/plaintime/until/index.md

files/en-us/web/javascript/reference/global_objects/temporal/plainyearmonth/since/index.md

files/en-us/web/javascript/reference/global_objects/temporal/zoneddatetime/round/index.md

files/en-us/web/javascript/reference/global_objects/temporal/instant/since/index.md

meyerweb

Temporal.PlainMonthDay and Temporal.PlainYearMonth constructors

files/en-us/web/javascript/reference/global_objects/temporal/plainmonthday/from/index.md

files/en-us/web/javascript/reference/global_objects/temporal/plainmonthday/with/index.md

...n-us/web/javascript/reference/global_objects/temporal/plainyearmonth/plainyearmonth/index.md

files/en-us/web/javascript/reference/global_objects/temporal/plainyearmonth/from/index.md

files/en-us/web/javascript/reference/global_objects/temporal/plainyearmonth/with/index.md

meyerweb

Temporal.ZonedDateTime constructors

files/en-us/web/javascript/reference/global_objects/temporal/zoneddatetime/from/index.md

files/en-us/web/javascript/reference/global_objects/temporal/zoneddatetime/with/index.md

...s/en-us/web/javascript/reference/global_objects/temporal/zoneddatetime/withcalendar/index.md

.../en-us/web/javascript/reference/global_objects/temporal/zoneddatetime/withplaintime/index.md

bsmth

Only one comment for Calendar: month-related group

files/en-us/web/javascript/reference/global_objects/temporal/plainyearmonth/monthcode/index.md

github-actions · 2025-01-14T17:21:24Z

This pull request has merge conflicts that must be resolved before it can be merged.

.../en-us/web/javascript/reference/global_objects/temporal/plainmonthday/plainmonthday/index.md

bsmth

Couple of comments for Conversion group, nearly there

bsmth · 2025-01-15T16:50:45Z

...s/en-us/web/javascript/reference/global_objects/temporal/instant/tozoneddatetimeiso/index.md

+console.log(zonedDateTime.toString()); // 2021-08-01T08:34:56.123456789-04:00[America/New_York]
+
+const localDateTime = instant.toZonedDateTimeISO(Temporal.Now.timeZoneId());
+console.log(zonedDateTime.toString()); // This instant in your timezone


copy paste err?

Suggested change

console.log(zonedDateTime.toString()); // This instant in your timezone

console.log(localDateTime.toString()); // This instant in your timezone

bsmth · 2025-01-15T17:10:52Z

...n-us/web/javascript/reference/global_objects/temporal/plaindatetime/tozoneddatetime/index.md

+
+```js
+const dtNotExist = Temporal.PlainDateTime.from("2024-03-10T02:05:00");
+// This wall-clock time never existed. So we need to choose from 01:05:00-05:00 or 03:05:00-04:00.


Do you want to mention "due to DST changeover" in the comment?

I find the interleaving ambiguous and not-existing examples is a little hard to follow, but leave if you prefer it.

bsmth · 2025-01-15T17:32:02Z

...n-us/web/javascript/reference/global_objects/temporal/zoneddatetime/toplaindatetime/index.md

+The **`toPlainDateTime()`** method of {{jsxref("Temporal.ZonedDateTime")}} instances returns a new {{jsxref("Temporal.PlainDateTime")}} object representing the date and time portions of this date-time. Only the time zone information is removed.
+
+> [!WARNING]
+> After a `Temporal.ZonedDateTime` is converted to `Temporal.PlainDateTime`, it will no longer be aware of its time zone. This means that subsequent operations like arithmetic or with will not adjust for DST and may not yield the same results as equivalent operations with `Temporal.ZonedDateTime`. However, unless you perform those operations across a time zone offset transition, it's impossible to notice the difference. Therefore, be very careful when performing this conversion because subsequent results may look correct most of the time while failing around time zone transitions like when DST starts or ends.


Minor one if you like:

Suggested change

> After a `Temporal.ZonedDateTime` is converted to `Temporal.PlainDateTime`, it will no longer be aware of its time zone. This means that subsequent operations like arithmetic or with will not adjust for DST and may not yield the same results as equivalent operations with `Temporal.ZonedDateTime`. However, unless you perform those operations across a time zone offset transition, it's impossible to notice the difference. Therefore, be very careful when performing this conversion because subsequent results may look correct most of the time while failing around time zone transitions like when DST starts or ends.

> After a `Temporal.ZonedDateTime` is converted to `Temporal.PlainDateTime`, it's no longer time zone aware. Subsequent operations like arithmetic or `with` operations will not adjust for DST and may not yield the same results as equivalent operations with `Temporal.ZonedDateTime`. However, unless you perform those operations across a time zone offset transition, it's impossible to notice the difference. Be very careful when performing this conversion because subsequent results may be correct most of the time, but incorrect across time zone transitions like when DST starts or ends.

bsmth · 2025-01-15T17:36:54Z

files/en-us/web/javascript/reference/global_objects/temporal/zoneddatetime/toplaintime/index.md

+{{JSRef}}
+
+The **`toPlainTime()`** method of {{jsxref("Temporal.ZonedDateTime")}} instances returns a new {{jsxref("Temporal.PlainTime")}} object representing the time portion of this date-time.
+


Is the warning like on toplaindatetime also useful regarding accuracy of subsequent calculations across DST boundaries, etc?

Reference for stage 3 temporal

27a3784

github-actions bot added Content:JS JavaScript docs size/xl [PR only] >1000 LoC changed labels Dec 23, 2024

More description

a477fa3

Josh-Cena mentioned this pull request Dec 25, 2024

What's the plan to get Temporal docs into MDN? tc39/proposal-temporal#1449

Open

Josh-Cena added 16 commits December 25, 2024 21:28

Duration docs

9f50952

Fix link

bd0796c

Complete Duration docs

fbd0601

Instant docs

6ab2afd

Now docs

ef79211

TZ and calendar docs

02295b7

PlainDate docs

0936403

Change ISO format description

889b358

ZonedDateTime-specific stuff docs

7ca2b31

PlainMonthDay docs, copy date-related fields to PlainDateTime

7d9cdfe

PlainYearMonth docs

a0ab015

PlainTime docs

f4342cf

Intl docs

4974d24

PlainDateTime docs

0a172b6

ZonedDateTime docs, easy part

ac18c5f

ZonedDateTime docs... and that shall be all

ac298ef

Josh-Cena mentioned this pull request Jan 3, 2025

feat(sidebars/jsref): support temporal mdn/rari#72

Merged

Simplifications and fixes

f385d12

Josh-Cena force-pushed the temporal branch from 7daf469 to f385d12 Compare January 3, 2025 09:04

Josh-Cena marked this pull request as ready for review January 3, 2025 09:04

Josh-Cena requested a review from a team as a code owner January 3, 2025 09:04

Josh-Cena requested review from chrisdavidmills and hamishwillee and removed request for a team January 3, 2025 09:04

Reviews

0b7b04d

bsmth reviewed Jan 10, 2025

View reviewed changes

Reviews, Temporal.Now

ce86a53

meyerweb reviewed Jan 10, 2025

View reviewed changes

Josh-Cena added 2 commits January 10, 2025 15:05

Mention precision of Temporal.Now methods

e28fc82

Reviews, landing pages

6756d76

meyerweb suggested changes Jan 10, 2025

View reviewed changes

Apply suggestions from code review

fc28f6b

Co-authored-by: Eric A. Meyer <[email protected]>

chrisdavidmills approved these changes Jan 13, 2025

View reviewed changes

bsmth reviewed Jan 13, 2025

View reviewed changes

files/en-us/web/javascript/reference/global_objects/temporal/zoneddatetime/timezoneid/index.md Outdated Show resolved Hide resolved

bsmth reviewed Jan 13, 2025

View reviewed changes

files/en-us/web/javascript/reference/global_objects/temporal/zoneddatetime/minute/index.md Show resolved Hide resolved

meyerweb suggested changes Jan 13, 2025

View reviewed changes

Time zone / calendar / time components

2e7b76a

meyerweb suggested changes Jan 13, 2025

View reviewed changes

Reviews, other constructors

2ebbb0e

bsmth reviewed Jan 14, 2025

View reviewed changes

meyerweb suggested changes Jan 14, 2025

View reviewed changes

bsmth reviewed Jan 14, 2025

View reviewed changes

files/en-us/web/javascript/reference/global_objects/temporal/plainyearmonth/monthcode/index.md Show resolved Hide resolved

Reviews, other constructors, arithmetic, monthCode

0f7231a

github-actions bot added the merge conflicts 🚧 [PR only] label Jan 14, 2025

Merge branch 'main' into temporal

627cdeb

github-actions bot removed the merge conflicts 🚧 [PR only] label Jan 14, 2025

Josh-Cena commented Jan 14, 2025

View reviewed changes

.../en-us/web/javascript/reference/global_objects/temporal/plainmonthday/plainmonthday/index.md Outdated Show resolved Hide resolved

Josh-Cena added 3 commits January 14, 2025 14:06

Update index.md

bf72961

Update index.md

0ca21c0

Update index.md

25e1bb1

bsmth reviewed Jan 15, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[new-ci] Reference for stage 3 temporal #37344

[new-ci] Reference for stage 3 temporal #37344

Josh-Cena commented Dec 23, 2024 •

edited

Loading

github-actions bot commented Dec 23, 2024 •

edited

Loading

bsmth left a comment

meyerweb left a comment

meyerweb left a comment

chrisdavidmills left a comment

bsmth left a comment

bsmth left a comment

meyerweb left a comment

meyerweb left a comment

meyerweb left a comment

bsmth left a comment

meyerweb left a comment

meyerweb left a comment

bsmth left a comment

github-actions bot commented Jan 14, 2025

bsmth left a comment

bsmth Jan 15, 2025

bsmth Jan 15, 2025

bsmth Jan 15, 2025

bsmth Jan 15, 2025 •

edited

Loading

bsmth Jan 15, 2025

	console.log(zonedDateTime.toString()); // This instant in your timezone
	console.log(localDateTime.toString()); // This instant in your timezone

		{{JSRef}}

		The `toPlainTime()` method of {{jsxref("Temporal.ZonedDateTime")}} instances returns a new {{jsxref("Temporal.PlainTime")}} object representing the time portion of this date-time.

[new-ci] Reference for stage 3 temporal #37344

Are you sure you want to change the base?

[new-ci] Reference for stage 3 temporal #37344

Conversation

Josh-Cena commented Dec 23, 2024 • edited Loading

github-actions bot commented Dec 23, 2024 • edited Loading

bsmth left a comment

Choose a reason for hiding this comment

meyerweb left a comment

Choose a reason for hiding this comment

meyerweb left a comment

Choose a reason for hiding this comment

chrisdavidmills left a comment

Choose a reason for hiding this comment

bsmth left a comment

Choose a reason for hiding this comment

bsmth left a comment

Choose a reason for hiding this comment

meyerweb left a comment

Choose a reason for hiding this comment

meyerweb left a comment

Choose a reason for hiding this comment

meyerweb left a comment

Choose a reason for hiding this comment

bsmth left a comment

Choose a reason for hiding this comment

meyerweb left a comment

Choose a reason for hiding this comment

meyerweb left a comment

Choose a reason for hiding this comment

bsmth left a comment

Choose a reason for hiding this comment

github-actions bot commented Jan 14, 2025

bsmth left a comment

Choose a reason for hiding this comment

bsmth Jan 15, 2025

Choose a reason for hiding this comment

bsmth Jan 15, 2025

Choose a reason for hiding this comment

bsmth Jan 15, 2025

Choose a reason for hiding this comment

bsmth Jan 15, 2025 • edited Loading

Choose a reason for hiding this comment

bsmth Jan 15, 2025

Choose a reason for hiding this comment

Josh-Cena commented Dec 23, 2024 •

edited

Loading

github-actions bot commented Dec 23, 2024 •

edited

Loading

bsmth Jan 15, 2025 •

edited

Loading