[Suspense] Document what activates a boundary, with live examples (#8505)

* [Suspense] Add 'What activates a Suspense boundary' section

* [Suspense] Clarify image activation wording (review feedback)

* Define "suspense-enabled-framework"

* Update outdated framework-less data fetching note to reference use()

* fix: clarify Suspense boundary activation and fallback behavior

* Add code example

* update styling

* Cleanup caveat

* add link to blogpost

* Replace notes with link to suspense docs

* Tweak caveat

* Update caveat to clarify streaming behavior during server rendering

* Address feedback

* address feedback

* Clarify documentation on Suspense-enabled frameworks

* Update links and wording

* Improve example

* Clarify heading for Suspense-enabled frameworks section

* Restructure page

* Update to be docs compliant and clarify images

* Address review feedback

* Add more suspense examples

* Add more examples

* Clarify image loading behavior during <ViewTransition> updates in Suspense documentation

* Enhance Suspense documentation with additional details on font and image loading during <ViewTransition> updates

* Update

* Enhance Suspense documentation with examples of stylesheet loading behavior and vanilla DOM comparison

* agent review

Author: aurorascharff

src/content/reference/react-dom/server/renderToPipeableStream.md

@@ -284,17 +284,7 @@ Streaming does not need to wait for React itself to load in the browser, or for
 
 <Note>
 
-**Only Suspense-enabled data sources will activate the Suspense component.** They include:
-
-- Data fetching with Suspense-enabled frameworks like [Relay](https://relay.dev/docs/guided-tour/rendering/loading-states/) and [Next.js](https://nextjs.org/docs/getting-started/react-essentials)
-- Lazy-loading component code with [`lazy`](/reference/react/lazy)
-- Reading the value of a Promise with [`use`](/reference/react/use)
-
-Suspense **does not** detect when data is fetched inside an Effect or event handler.
-
-The exact way you would load data in the `Posts` component above depends on your framework. If you use a Suspense-enabled framework, you'll find the details in its data fetching documentation.
-
-Suspense-enabled data fetching without the use of an opinionated framework is not yet supported. The requirements for implementing a Suspense-enabled data source are unstable and undocumented. An official API for integrating data sources with Suspense will be released in a future version of React.
+Only data read from a source that [activates a Suspense boundary](/reference/react/Suspense#what-activates-a-suspense-boundary), such as a Promise read with [`use`](/reference/react/use), will suspend during rendering. Suspense does not detect data fetched inside an Effect or event handler.
 
 </Note>
 

src/content/reference/react-dom/server/renderToReadableStream.md

@@ -283,17 +283,7 @@ Streaming does not need to wait for React itself to load in the browser, or for
 
 <Note>
 
-**Only Suspense-enabled data sources will activate the Suspense component.** They include:
-
-- Data fetching with Suspense-enabled frameworks like [Relay](https://relay.dev/docs/guided-tour/rendering/loading-states/) and [Next.js](https://nextjs.org/docs/getting-started/react-essentials)
-- Lazy-loading component code with [`lazy`](/reference/react/lazy)
-- Reading the value of a Promise with [`use`](/reference/react/use)
-
-Suspense **does not** detect when data is fetched inside an Effect or event handler.
-
-The exact way you would load data in the `Posts` component above depends on your framework. If you use a Suspense-enabled framework, you'll find the details in its data fetching documentation.
-
-Suspense-enabled data fetching without the use of an opinionated framework is not yet supported. The requirements for implementing a Suspense-enabled data source are unstable and undocumented. An official API for integrating data sources with Suspense will be released in a future version of React.
+Only data read from a source that [activates a Suspense boundary](/reference/react/Suspense#what-activates-a-suspense-boundary), such as a Promise read with [`use`](/reference/react/use), will suspend during rendering. Suspense does not detect data fetched inside an Effect or event handler.
 
 </Note>
 

src/content/reference/react-dom/static/prerender.md

@@ -275,17 +275,7 @@ Imagine that `<Posts />` needs to load some data, which takes some time. Ideally
 
 <Note>
 
-**Only Suspense-enabled data sources will activate the Suspense component.** They include:
-
-- Data fetching with Suspense-enabled frameworks like [Relay](https://relay.dev/docs/guided-tour/rendering/loading-states/) and [Next.js](https://nextjs.org/docs/getting-started/react-essentials)
-- Lazy-loading component code with [`lazy`](/reference/react/lazy)
-- Reading the value of a Promise with [`use`](/reference/react/use)
-
-Suspense **does not** detect when data is fetched inside an Effect or event handler.
-
-The exact way you would load data in the `Posts` component above depends on your framework. If you use a Suspense-enabled framework, you'll find the details in its data fetching documentation.
-
-Suspense-enabled data fetching without the use of an opinionated framework is not yet supported. The requirements for implementing a Suspense-enabled data source are unstable and undocumented. An official API for integrating data sources with Suspense will be released in a future version of React.
+Only data read from a source that [activates a Suspense boundary](/reference/react/Suspense#what-activates-a-suspense-boundary), such as a Promise read with [`use`](/reference/react/use), will suspend during rendering. Suspense does not detect data fetched inside an Effect or event handler.
 
 </Note>
 

src/content/reference/react-dom/static/prerenderToNodeStream.md

@@ -276,17 +276,7 @@ Imagine that `<Posts />` needs to load some data, which takes some time. Ideally
 
 <Note>
 
-**Only Suspense-enabled data sources will activate the Suspense component.** They include:
-
-- Data fetching with Suspense-enabled frameworks like [Relay](https://relay.dev/docs/guided-tour/rendering/loading-states/) and [Next.js](https://nextjs.org/docs/getting-started/react-essentials)
-- Lazy-loading component code with [`lazy`](/reference/react/lazy)
-- Reading the value of a Promise with [`use`](/reference/react/use)
-
-Suspense **does not** detect when data is fetched inside an Effect or event handler.
-
-The exact way you would load data in the `Posts` component above depends on your framework. If you use a Suspense-enabled framework, you'll find the details in its data fetching documentation.
-
-Suspense-enabled data fetching without the use of an opinionated framework is not yet supported. The requirements for implementing a Suspense-enabled data source are unstable and undocumented. An official API for integrating data sources with Suspense will be released in a future version of React.
+Only data read from a source that [activates a Suspense boundary](/reference/react/Suspense#what-activates-a-suspense-boundary), such as a Promise read with [`use`](/reference/react/use), will suspend during rendering. Suspense does not detect data fetched inside an Effect or event handler.
 
 </Note>
 

src/content/reference/react/Activity.md

@@ -755,17 +755,7 @@ Pre-rendering components with hidden Activity boundaries is a powerful way to re
 
 <Note>
 
-**Only Suspense-enabled data sources will be fetched during pre-rendering.** They include:
-
-- Data fetching with Suspense-enabled frameworks like [Relay](https://relay.dev/docs/guided-tour/rendering/loading-states/) and [Next.js](https://nextjs.org/docs/app/building-your-application/routing/loading-ui-and-streaming#streaming-with-suspense)
-- Lazy-loading component code with [`lazy`](/reference/react/lazy)
-- Reading the value of a cached Promise with [`use`](/reference/react/use)
-
-Activity **does not** detect data that is fetched inside an Effect.
-
-The exact way you would load data in the `Posts` component above depends on your framework. If you use a Suspense-enabled framework, you'll find the details in its data fetching documentation.
-
-Suspense-enabled data fetching without the use of an opinionated framework is not yet supported. The requirements for implementing a Suspense-enabled data source are unstable and undocumented. An official API for integrating data sources with Suspense will be released in a future version of React.
+Only data read from a source that [activates a Suspense boundary](/reference/react/Suspense#what-activates-a-suspense-boundary), such as a Promise read with [`use`](/reference/react/use), is fetched during pre-rendering. Activity does not detect data fetched inside an Effect.
 
 </Note>