From 61952ed0f94d2627472b0c50aa920ef0b7b2daa3 Mon Sep 17 00:00:00 2001
From: Jack Pope <jackpope@meta.com>
Date: Fri, 24 May 2024 09:52:56 +0100
Subject: [PATCH] Update structure based on feedback

---
 src/content/reference/react/act.md | 33 ++++++++++++++++++++++++------
 1 file changed, 27 insertions(+), 6 deletions(-)

diff --git a/src/content/reference/react/act.md b/src/content/reference/react/act.md
index 4107e7ba503..dc29535a7fe 100644
--- a/src/content/reference/react/act.md
+++ b/src/content/reference/react/act.md
@@ -4,25 +4,46 @@ title: act
 
 <Intro>
 
-To prepare a component for assertions, wrap the code rendering it and performing updates inside an act() call. This makes your test run closer to how React works in the browser.
+`act` lets you wrap rendering and updates in tests to ensure changes are applied to the DOM before making assertions.
+
+```js
+act(updateFn)
+```
 
 </Intro>
 
+To prepare a component for assertions, wrap the code rendering it and performing updates inside an `act()` call. This makes your test run closer to how React works in the browser.
+
+
 <InlineToc />
 
 ---
 
+## Reference {/*reference*/}
+
+### `act(updateFn)` {/*actupdatefn*/}
+
 When writing UI tests, tasks like rendering, user events, or data fetching can be considered as “units” of interaction with a user interface. React provides a helper called `act()` that makes sure all updates related to these “units” have been processed and applied to the DOM before you make any assertions.
 
 The name `act` comes from the [Arrange-Act-Assert](https://wiki.c2.com/?ArrangeActAssert) pattern.
 
-```js
-act(() => {
-  // render components
+```js {2,4}
+it ('renders with button disabled', () => {
+  act(() => {
+    root.render(<TestComponent />)
+  });
+  expect(container.querySelector('button')).toBeDisabled();
 });
-// make assertions
 ```
 
+#### Parameters {/*parameters*/}
+
+* `updateFn`: A function wrapping renders or interactions for components being tested. Any updates triggered within the `updateFn` are added to an internal act queue, which are then flushed together to process and apply any changes to the DOM.
+
+#### Returns {/*returns*/}
+
+`act` does not return anything.
+
 ## Usage {/*usage*/}
 
 <Note>
@@ -55,7 +76,7 @@ function Counter() {
 
 Here is how we can test it:
 
-```js
+```js  {19,21,28,30}
 import React from 'react';
 import ReactDOM from 'react-dom/client';
 import Counter from './Counter';