Adds docs for notRestoredReasons

[chrisdavidmills]

Note: This technical review is now completed and approved. For the follow-on editorial review, see #32920

---

Description

The PerformanceNavigationTiming.notRestoredReasons property (see Back/forward cache notRestoredReasons API) is finally going to be launched in Chrome 123. This PR adds a reference page for the property and associated interfaces, and a guide to using it.

Motivation

Additional details

Related issues and pull requests

[github-actions]

Preview URLs (15 pages)

• /en-US/docs/Web/API/NotRestoredReasonDetails/reason
• /en-US/docs/Web/API/NotRestoredReasonDetails/toJSON
• /en-US/docs/Web/API/NotRestoredReasonDetails
• /en-US/docs/Web/API/NotRestoredReasons/children
• /en-US/docs/Web/API/NotRestoredReasons/id
• /en-US/docs/Web/API/NotRestoredReasons/name
• /en-US/docs/Web/API/NotRestoredReasons/reasons
• /en-US/docs/Web/API/NotRestoredReasons/src
• /en-US/docs/Web/API/NotRestoredReasons/toJSON
• /en-US/docs/Web/API/NotRestoredReasons/url
• /en-US/docs/Web/API/NotRestoredReasons
• /en-US/docs/Web/API/PerformanceNavigationTiming/notRestoredReasons
• /en-US/docs/Web/API/PerformanceNavigationTiming
• /en-US/docs/Web/API/Performance_API/Reporting_backforward_cache_not_restored_reasons
• /en-US/docs/Web/API/Performance_API

Flaws (13)

Note! 2 documents with no flaws that don't need to be listed. 🎉

URL: /en-US/docs/Web/API/PerformanceNavigationTiming/notRestoredReasons
Title: PerformanceNavigationTiming: notRestoredReasons property
Flaw count: 1

• bad_bcd_queries:
  • No BCD data for query: api.PerformanceNavigationTiming.notRestoredReasons

---

URL: /en-US/docs/Web/API/NotRestoredReasonDetails
Title: NotRestoredReasonDetails
Flaw count: 1

• bad_bcd_queries:
  • No BCD data for query: api.NotRestoredReasonDetails

---

URL: /en-US/docs/Web/API/NotRestoredReasonDetails/toJSON
Title: NotRestoredReasonDetails: toJSON() method
Flaw count: 1

• bad_bcd_queries:
  • No BCD data for query: api.NotRestoredReasonDetails.toJSON

---

URL: /en-US/docs/Web/API/NotRestoredReasonDetails/reason
Title: NotRestoredReasonDetails: reason property
Flaw count: 1

• bad_bcd_queries:
  • No BCD data for query: api.NotRestoredReasonDetails.reason

---

URL: /en-US/docs/Web/API/Performance_API/Reporting_backforward_cache_not_restored_reasons
Title: Reporting back/forward cache not restored reasons
Flaw count: 1

• bad_bcd_queries:
  • No BCD data for query: api.PerformanceNavigationTiming.notRestoredReasons

---

URL: /en-US/docs/Web/API/NotRestoredReasons
Title: NotRestoredReasons
Flaw count: 1

• bad_bcd_queries:
  • No BCD data for query: api.NotRestoredReasons

---

URL: /en-US/docs/Web/API/NotRestoredReasons/toJSON
Title: NotRestoredReasons: toJSON() method
Flaw count: 1

• bad_bcd_queries:
  • No BCD data for query: api.NotRestoredReasons.toJSON

---

URL: /en-US/docs/Web/API/NotRestoredReasons/name
Title: NotRestoredReasons: name property
Flaw count: 1

• bad_bcd_queries:
  • No BCD data for query: api.NotRestoredReasons.name

---

URL: /en-US/docs/Web/API/NotRestoredReasons/children
Title: NotRestoredReasons: children property
Flaw count: 1

• bad_bcd_queries:
  • No BCD data for query: api.NotRestoredReasons.children

---

URL: /en-US/docs/Web/API/NotRestoredReasons/id
Title: NotRestoredReasons: id property
Flaw count: 1

• bad_bcd_queries:
  • No BCD data for query: api.NotRestoredReasons.id

---

URL: /en-US/docs/Web/API/NotRestoredReasons/url
Title: NotRestoredReasons: url property
Flaw count: 1

• bad_bcd_queries:
  • No BCD data for query: api.NotRestoredReasons.url

---

URL: /en-US/docs/Web/API/NotRestoredReasons/src
Title: NotRestoredReasons: src property
Flaw count: 1

• bad_bcd_queries:
  • No BCD data for query: api.NotRestoredReasons.src

---

URL: /en-US/docs/Web/API/NotRestoredReasons/reasons
Title: NotRestoredReasons: reasons property
Flaw count: 1

• bad_bcd_queries:
  • No BCD data for query: api.NotRestoredReasons.reasons

External URLs (11)

URL: /en-US/docs/Web/API/PerformanceNavigationTiming
Title: PerformanceNavigationTiming

• https://web.dev/articles/bfcache (1 time) (Note! This may be a new URL 👀)

---

URL: /en-US/docs/Web/API/PerformanceNavigationTiming/notRestoredReasons
Title: PerformanceNavigationTiming: notRestoredReasons property

• https://web.dev/articles/bfcache (1 time) (Note! This may be a new URL 👀)

---

URL: /en-US/docs/Web/API/NotRestoredReasonDetails
Title: NotRestoredReasonDetails

• https://web.dev/articles/bfcache (1 time) (Note! This may be a new URL 👀)

---

URL: /en-US/docs/Web/API/NotRestoredReasonDetails/reason
Title: NotRestoredReasonDetails: reason property

• https://developer.chrome.com/docs/web-platform/deprecating-unload (1 time) (Note! This may be a new URL 👀)
• https://web.dev/articles/bfcache (1 time) (Note! This may be a new URL 👀)

---

URL: /en-US/docs/Web/API/Performance_API
Title: Performance APIs

• https://web.dev/bfcache/ (1 time) (Note! This may be a new URL 👀)

---

URL: /en-US/docs/Web/API/Performance_API/Reporting_backforward_cache_not_restored_reasons
Title: Reporting back/forward cache not restored reasons

• https://developer.chrome.com/docs/web-platform/deprecating-unload (1 time) (Note! This may be a new URL 👀)
• https://github.com/WICG/bfcache-not-restored-reason/blob/main/NotRestoredReason.md (1 time) (Note! This may be a new URL 👀)
• https://web.dev/bfcache/ (3 times) (Note! This may be a new URL 👀)

---

URL: /en-US/docs/Web/API/NotRestoredReasons
Title: NotRestoredReasons

• https://web.dev/articles/bfcache (1 time) (Note! This may be a new URL 👀)

---

URL: /en-US/docs/Web/API/NotRestoredReasons/reasons
Title: NotRestoredReasons: reasons property

• https://web.dev/articles/bfcache (1 time) (Note! This may be a new URL 👀)

(comment last updated: 2024-03-29 11:30:17)

[tunetheweb]

Is it possible to add to the browser compat repo too?

[chrisdavidmills]

Is it possible to add to the browser compat repo too?

@tunetheweb I've done so; see mdn/browser-compat-data#20361

[tunetheweb]

LGTM! I've asked the devs to review as well.

[rubberyuzu]

Thanks for working on this!
Sorry the explainer is a bit out of date and it needs some work around masking cross-origin frames. I will update it later.

1. blocked is going to be called preventedBackForwardCache, and the possible value is "masked", "yes" and "no". Can you please update around blocked to reflect it? You can refer to this PR: Add back/forward cache NotRestoredReasons whatwg/html#9360

2. url, reasons and children can be null for cross-origin frames. (We are currently discussing whether we mask them all or only partially. Please refer to the PR thread above.)

[tunetheweb]

Thanks @rubberyuzu !

@chrisdavidmills this also answers the question of the spec - it will be added to the HTML spec once whatwg/html#9360 is merged and does list a set of reasons. Maybe we're better putting this back into draft until that lands and then update this PR appropriately?

[chrisdavidmills]

Thanks @rubberyuzu !

@chrisdavidmills this also answers the question of the spec - it will be added to the HTML spec once whatwg/html#9360 is merged and does list a set of reasons. Maybe we're better putting this back into draft until that lands and then update this PR appropriately?

Yes, it would definitely be good to wait until this is in the spec. I'll put this into draft status for now.

Thanks for the input, @rubberyuzu and @tunetheweb

[github-actions]

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

[tunetheweb]

LGTM now. Thanks for addressing the feedback!

[chrisdavidmills]

@tunetheweb great, thanks for the review. I'm calling the tech review completed. Next stage is to close this PR, and open a new PR based on the same branch to contain the editorial review.