npm - @conduction/docusaurus-preset - Versions diffs - 3.9.0 → 3.10.0 - Mend

@conduction/docusaurus-preset 3.9.0 → 3.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (7) hide show

package/package.json +1 -1
package/src/components/Clients/Clients.jsx +2 -4
package/src/components/HexRain/HexRain.jsx +11 -14
package/src/components/PlatformDiagram/PlatformDiagram.jsx +9 -10
package/src/components/PlatformOverview/PlatformOverview.jsx +3 -9
package/src/theme/Footer/index.jsx +15 -17
package/src/utils/lazyStylesheet.js +42 -0

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@conduction/docusaurus-preset",
-  "version": "3.9.0",
+  "version": "3.10.0",
   "scripts": {
     "prepack": "node scripts/prepack-bundle-css.js"
   },

package/src/components/Clients/Clients.jsx CHANGED Viewed

@@ -20,7 +20,7 @@
  */
 import React from 'react';
-import Head from '@docusaurus/Head';
+import {useLazyStylesheet} from '../../utils/lazyStylesheet';
 import SectionHead from '../primitives/SectionHead';
 import {useLazyScript} from '../../utils/lazyScript';
 import styles from './Clients.module.css';
@@ -121,6 +121,7 @@ function splitIntoRows(items, rowCount) {
 function ClientsMarquee({head, clients, title, className}) {
   useLazyScript(LOGO_MEMORY_BASE + '/clients-flow.js', 'clients-flow');
   useLazyScript(LOGO_MEMORY_BASE + '/logo-memory.js', 'logo-memory');
+  useLazyStylesheet(LOGO_MEMORY_BASE + '/logo-memory.css', 'logo-memory');
   React.useEffect(() => {
     if (window.ConductionClientsFlow?.hydrate) window.ConductionClientsFlow.hydrate();
     if (window.LogoMemory?.hydrate) window.LogoMemory.hydrate();
@@ -128,9 +129,6 @@ function ClientsMarquee({head, clients, title, className}) {
   const clientsJson = React.useMemo(() => JSON.stringify(clients), [clients]);
   return (
     <>
-      <Head>
-        <link rel="stylesheet" href={LOGO_MEMORY_BASE + '/logo-memory.css'} />
-      </Head>
       <section
         className={[styles.section, className].filter(Boolean).join(' ')}
         data-logo-memory

package/src/components/HexRain/HexRain.jsx CHANGED Viewed

@@ -33,9 +33,9 @@
  */
 import React, {useEffect, useRef} from 'react';
-import Head from '@docusaurus/Head';
 import useIsBrowser from '@docusaurus/useIsBrowser';
 import {useLazyScript} from '../../utils/lazyScript';
+import {useLazyStylesheet} from '../../utils/lazyStylesheet';
 const ASSET_BASE = '/lib';
@@ -43,10 +43,12 @@ export default function HexRain({ariaLabel = 'Twelve apps mini-game, click each
   const isBrowser = useIsBrowser();
   const ref = useRef(null);
-  /* hex-rain.js is loaded post-hydration via this hook so the runtime's
-     DOM mutations don't trip React's hydration mismatch. See
-     utils/lazyScript.js. */
+  /* hex-rain.{js,css} are loaded post-hydration so neither the
+     runtime's DOM mutations trip React's hydration mismatch nor the
+     stylesheet blocks first paint. See utils/lazyScript.js and
+     utils/lazyStylesheet.js. */
   useLazyScript(ASSET_BASE + '/hex-rain.js', 'hex-rain');
+  useLazyStylesheet(ASSET_BASE + '/hex-rain.css', 'hex-rain');
   /* The runtime exposes window.HexRain.hydrate() once it has registered
      itself. Poll one rAF tick per frame until it's there, then call it
@@ -67,15 +69,10 @@ export default function HexRain({ariaLabel = 'Twelve apps mini-game, click each
   }, [isBrowser]);
   return (
-    <>
-      <Head>
-        <link rel="stylesheet" href={ASSET_BASE + '/hex-rain.css'} />
-      </Head>
-      <div
-        ref={ref}
-        className={['hex-rain', className].filter(Boolean).join(' ')}
-        aria-label={ariaLabel}
-      />
-    </>
+    <div
+      ref={ref}
+      className={['hex-rain', className].filter(Boolean).join(' ')}
+      aria-label={ariaLabel}
+    />
   );
 }

package/src/components/PlatformDiagram/PlatformDiagram.jsx CHANGED Viewed

@@ -44,25 +44,24 @@
  */
 import React from 'react';
-import Head from '@docusaurus/Head';
 import {useLazyScript} from '../../utils/lazyScript';
+import {useLazyStylesheet} from '../../utils/lazyStylesheet';
 const ASSET_BASE = '/lib';
 export default function PlatformDiagram({workspace, lists = [], flows = []}) {
-  /* platform-diagram.js is loaded post-hydration. The runtime registers
-     a custom-element definition that upgrades any <platform-diagram>
-     element on the page; running it after React hydration prevents the
-     custom-element constructor from mutating the DOM mid-hydration and
-     producing #418 / #423 warnings. See utils/lazyScript.js. */
+  /* platform-diagram.{js,css} are loaded post-hydration. The runtime
+     registers a custom-element definition that upgrades any
+     <platform-diagram> element on the page; running it after React
+     hydration prevents the custom-element constructor from mutating the
+     DOM mid-hydration and producing #418 / #423 warnings. The matching
+     stylesheet is held off the render path so its 19 KB doesn't block
+     LCP on pages that render this component. */
   useLazyScript(ASSET_BASE + '/platform-diagram.js', 'platform-diagram');
+  useLazyStylesheet(ASSET_BASE + '/platform-diagram.css', 'platform-diagram');
   return (
     <>
-      <Head>
-        <link rel="stylesheet" href={ASSET_BASE + '/platform-diagram.css'} />
-      </Head>
       <platform-diagram>
         {workspace && (
           <pd-workspace

package/src/components/PlatformOverview/PlatformOverview.jsx CHANGED Viewed

@@ -6,22 +6,16 @@
  * "section-head" pattern (eyebrow + h2 + lede) above the diagram.
  *
  * The platform-diagram custom element is registered by
- * /lib/platform-diagram.js, which sites must include via <Head> on
- * any page that uses this section. The CSS is similarly served from
- * /lib/platform-diagram.css.
+ * /lib/platform-diagram.js and styled by /lib/platform-diagram.css.
+ * Both are loaded post-hydration by the <PlatformDiagram /> component;
+ * sites no longer need to inject anything in <Head> manually.
  *
  * Mirrors the .platform section in preview/pages/landing.html.
  *
  * Usage in MDX:
  *
- *   import Head from '@docusaurus/Head';
  *   import {PlatformOverview} from '@conduction/docusaurus-preset/components';
  *
- *   <Head>
- *     <link rel="stylesheet" href="/lib/platform-diagram.css" />
- *     <script src="/lib/platform-diagram.js" defer />
- *   </Head>
- *
  *   <PlatformOverview
  *     eyebrow="The platform"
  *     title={<>Five components.<br/>Twenty-four apps. One <span className="next-blue">Nextcloud</span> workspace.</>}

package/src/theme/Footer/index.jsx CHANGED Viewed

@@ -20,12 +20,12 @@
 import React, {useEffect} from 'react';
 import Link from '@docusaurus/Link';
-import Head from '@docusaurus/Head';
 import {useLocation} from '@docusaurus/router';
 import {useThemeConfig} from '@docusaurus/theme-common';
 import useIsBrowser from '@docusaurus/useIsBrowser';
 import {brandFor} from '../brand.jsx';
 import {useLazyScript} from '../../utils/lazyScript';
+import {useLazyStylesheet} from '../../utils/lazyStylesheet';
 import GameModal from '../../components/GameModal/GameModal';
 function FooterLink({label, href, to}) {
@@ -95,20 +95,23 @@ export default function Footer() {
   const wordmark = brand ? brand.wordmark : defaultWordmark;
   const brandRow = !brand && Array.isArray(footerBrand?.brands) ? footerBrand.brands : null;
-  /* canal-footer.js is loaded post-hydration so its DOM mutations
-     (filling .skyline, animating boats) don't trip React hydration
-     mismatches. See docs in utils/lazyScript.js. We always load
-     canal-footer.js even when minigames are off, because the same
-     script populates the static skyline; canal-footer.js is null-safe
-     against a missing game-hud, so the game wiring no-ops cleanly. */
+  /* canal-footer.{js,css} are loaded post-hydration. The script's DOM
+     mutations (filling .skyline, animating boats) don't trip React
+     hydration mismatches, and the stylesheet doesn't block first paint.
+     See docs in utils/lazyScript.js and utils/lazyStylesheet.js. We
+     always load canal-footer.{js,css} even when minigames are off,
+     because the same script populates the static skyline and the same
+     stylesheet styles the canal frame. */
   useLazyScript('/lib/canal-footer.js', 'canal-footer');
+  useLazyStylesheet('/lib/canal-footer.css', 'canal-footer');
-  /* kade-cyclist.js is the second hidden footer minigame. Unlike the
-     canal script it has no static side-effects, so when a product page
-     opts out of minigames we feed `useLazyScript` a falsy src to skip
-     the load. The hook still runs unconditionally — rules-of-hooks
-     stays compliant. */
+  /* kade-cyclist.{js,css} are the second hidden footer minigame. Unlike
+     the canal script they have no static side-effects, so when a product
+     page opts out of minigames we feed both hooks a falsy value to skip
+     the load. The hooks still run unconditionally — rules-of-hooks stays
+     compliant. */
   useLazyScript(minigamesOn ? '/lib/kade-cyclist.js' : null, 'kade-cyclist');
+  useLazyStylesheet(minigamesOn ? '/lib/kade-cyclist.css' : null, 'kade-cyclist');
   /* Re-hydrate the canal-footer + kade-cyclist runtimes on every mount,
      including SPA route changes that re-render this Footer component.
@@ -143,11 +146,6 @@ export default function Footer() {
   return (
     <>
-      <Head>
-        <link rel="stylesheet" href="/lib/canal-footer.css" />
-        <link rel="stylesheet" href="/lib/kade-cyclist.css" />
-      </Head>
       <footer className="canal-footer" aria-label="Site footer">
         {/* Skyline placeholder — canal-footer.js fills it with cloned house templates */}
         <div className="skyline" role="presentation" />

package/src/utils/lazyStylesheet.js ADDED Viewed

@@ -0,0 +1,42 @@
+/**
+ * useLazyStylesheet: load a runtime stylesheet after React hydration.
+ *
+ * Mirror of useLazyScript for CSS. The preset's heavier decorative
+ * stylesheets (canal-footer, kade-cyclist, hex-rain, logo-memory,
+ * platform-diagram) were injected via `<Head><link rel="stylesheet" />`,
+ * which Docusaurus SSGs into the rendered `<head>` and the browser
+ * treats as render-blocking. With five of these on a site that loads
+ * any landing page, LCP and TBT both regress past the "good" CWV
+ * threshold (LCP < 2.5s, INP < 200ms).
+ *
+ * Injecting via useEffect moves the load past hydration, so the
+ * stylesheet downloads in parallel with first paint instead of
+ * blocking it. Trade-off: a brief style-less flash before the CSS
+ * applies. Mitigated for above-fold callers by inlining the small
+ * structural rules into brand.css and only lazy-loading the
+ * decorative parts.
+ *
+ * The injected link has data-lazy-stylesheet="<key>" so SPA route
+ * changes don't double-inject, mirroring useLazyScript's idempotency.
+ */
+import {useEffect} from 'react';
+import useIsBrowser from '@docusaurus/useIsBrowser';
+/**
+ * Pass a falsy `href` to skip the load entirely. The hook still runs
+ * unconditionally so call sites stay rules-of-hooks-compliant.
+ */
+export function useLazyStylesheet(href, key) {
+  const isBrowser = useIsBrowser();
+  useEffect(() => {
+    if (!isBrowser) return;
+    if (!href) return;
+    if (document.querySelector(`link[data-lazy-stylesheet="${key}"]`)) return;
+    const link = document.createElement('link');
+    link.rel = 'stylesheet';
+    link.href = href;
+    link.dataset.lazyStylesheet = key;
+    document.head.appendChild(link);
+  }, [isBrowser, href, key]);
+}