Cleanup: Preload FontAwesome, fix comment grammar, audit NPM packages

_layouts/spec.html

@@ -9,6 +9,13 @@
         <meta name="viewport" content="width=device-width, initial-scale=1">
 {% seo %}
 
+        {%- comment -%}
+            The FontAwesome stylesheet is injected by Primer Spec to defer
+            loading. However, we can mitigate the icon-flashing by requesting
+            the browser to preload the stylesheet asynchronously asap.
+        {%- endcomment -%}
+        <link rel="preload" href="https://use.fontawesome.com/releases/v5.7.2/css/all.css" as="style" crossorigin="anonymous" integrity="sha384-fnmOCqbTlWIlj8LyTjo7mOUStjsKC4pOpQbqyi7RrhN7udi9RwhKkMHpvLbHG9Sr">
+
         {%- if site.favicon %}
         <link rel="icon" href="{{ site.favicon | relative_url }}">
         {%- endif %}

src_js/main.tsx

@@ -4,6 +4,9 @@ import PrimerSpec from './components/PrimerSpec';
 import Config from './Config';
 import { updateTheme } from './subthemes';
 
+/**
+ * The entry point to the Primer Spec JS.
+ */
 function main() {
   const anchors = new AnchorJS();
   anchors.add('h1');

src_js/utils/hooks/print.ts

@@ -1,7 +1,7 @@
 import { useCallback, useEffect, useState } from 'preact/hooks';
 
 /**
- * Returns a stateful boolean representing if a print-event is in progress
+ * Return a stateful boolean representing if a print-event is in progress
  * (between beforeprint and afterprint).
  */
 export function usePrintInProgress(): boolean {

src_js/utils/hooks/usePrefersDarkMode.ts

@@ -1,5 +1,10 @@
 import { useEffect, useState } from 'preact/hooks';
 
+/**
+ * Return a stateful boolean that describes whether the user's OS settings
+ * indicate a preference for light-themes or dark-themes. This preference is
+ * used when the subtheme mode is set to 'system'.
+ */
 export default function usePrefersDarkMode(): boolean {
   const [prefersDarkMode, setPrefersDarkMode] = useState(
     window.matchMedia('(prefers-color-scheme: dark)').matches,

src_js/utils/hooks/useSmallScreen.ts

@@ -1,6 +1,10 @@
 import { useLayoutEffect, useState } from 'preact/hooks';
 import isSmallScreen from '../isSmallScreen';
 
+/**
+ * Return a stateful boolean indicating whether the viewer's screen width is
+ * 'small' (as defined by `isSmallScreen()`).
+ */
 export default function useSmallScreen(): boolean {
   const [is_small_screen, setIsSmallScreen] = useState(isSmallScreen());
   useLayoutEffect(() => {

src_js/utils/hooks/useWindowLoaded.ts

@@ -1,7 +1,7 @@
 import { useEffect, useState } from 'preact/hooks';
 
 /**
- * Returns a stateful boolean that indicates whether all resources on the page
+ * Return a stateful boolean that indicates whether all resources on the page
  * have been downloaded (and the 'load' event will fire / has fired on the
  * window).
  */

src_js/utils/isSmallScreen.ts

@@ -1,5 +1,5 @@
 /**
- * Returns a boolean indicating whether the viewer's screen width is
+ * Return a boolean indicating whether the viewer's screen width is
  * smaller than 900px.
  */
 export default function isSmallScreen(): boolean {