Merge branch 'docs-update-note-about-dom-content-loaded' into 'master'

Update performance docs to reflect removal of `DOMContentLoaded` and usage of `waitForCSSLoaded`

See merge request gitlab-org/gitlab!46733

doc/development/fe_guide/performance.md

@@ -97,16 +97,26 @@ browser's developer console while on any page within GitLab.
   modules outside of the entry point script. Just import, read the DOM,
   instantiate, and nothing else.
 
-- **Entry Points May Be Asynchronous:**
-  _DO NOT ASSUME_ that the DOM has been fully loaded and available when an
-  entry point script is run. If you require that some code be run after the
-  DOM has loaded, you should attach an event handler to the `DOMContentLoaded`
-  event with:
+- **`DOMContentLoaded` should not be used:**
+  All of GitLab's JavaScript files are added with the `defer` attribute.
+  According to the [Mozilla documentation](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script#attr-defer),
+  this implies that "the script is meant to be executed after the document has
+  been parsed, but before firing `DOMContentLoaded`". Since the document is already
+  parsed, `DOMContentLoaded` is not needed to bootstrap applications because all
+  the DOM nodes are already at our disposal.
+
+- **JavaScript that relies on CSS for calculations should use [`waitForCSSLoaded()`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/assets/javascripts/helpers/startup_css_helper.js#L34):**
+  GitLab uses [Startup.css](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/38052)
+  to improve page performance. This can cause issues if JavaScript relies on CSS
+  for calculations. To fix this the JavaScript can be wrapped in the 
+  [`waitForCSSLoaded()`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/assets/javascripts/helpers/startup_css_helper.js#L34)
+  helper function.
 
   ```javascript
   import initMyWidget from './my_widget';
+  import { waitForCSSLoaded } from '~/helpers/startup_css_helper';
 
-  document.addEventListener('DOMContentLoaded', () => {
+  waitForCSSLoaded(() => {
     initMyWidget();
   });
   ```