From 4a08724c2903df81afb70ba56953b7e24bd22143 Mon Sep 17 00:00:00 2001
From: Guy Sartorelli <guy.sartorelli@silverstripe.com>
Date: Fri, 22 Jul 2022 12:18:04 +1200
Subject: [PATCH] NEW Add version banners at the top of docs pages

---
 purgecss.config.js                     |  8 +++-
 src/components/Layout.tsx              |  6 ++-
 src/components/NodeProvider.tsx        |  2 +
 src/hooks/useHierarchy.ts              |  3 +-
 src/theme/assets/scss/theme/_docs.scss | 54 ++++++++++++++++++++++++
 src/utils/nodes.ts                     | 58 ++++++++++++++++++++++++--
 src/utils/rewriteHeader.ts             |  7 ++++
 7 files changed, 131 insertions(+), 7 deletions(-)

diff --git a/purgecss.config.js b/purgecss.config.js
index 3b55584..26f820b 100644
--- a/purgecss.config.js
+++ b/purgecss.config.js
@@ -14,7 +14,7 @@ class IconExtractor {
         const matches = content.match(/icon(Brand)?: ([a-zA-Z0-9_-]+)/);
         if (matches) {
           const isBrand = typeof matches[1] !== 'undefined';
-          selectors.push(isBrand ? `fab` : `fas`);
+          selectors.push(isBrand ? 'fab' : 'fas');
           selectors.push(`fa-${matches[2]}`);
         }
         return selectors;
@@ -29,6 +29,12 @@ const whitelist = [
     // Syntax highlighting
     'pre',
     'code',
+
+    // Icon classes used in nodes.ts
+    'far',
+    'fa-calendar',
+    'fa-check-circle',
+    'fa-times-circle',
 ];
 
 const whitelistPatterns = [
diff --git a/src/components/Layout.tsx b/src/components/Layout.tsx
index b9039e4..2903cc8 100644
--- a/src/components/Layout.tsx
+++ b/src/components/Layout.tsx
@@ -11,13 +11,14 @@ interface LayoutProps {
   }
 }
 const Layout: StatelessComponent<LayoutProps> = ({ children, pageContext: { slug } }) => {
-  const { setCurrentPath, getVersionPath, getCurrentVersion, getCurrentNode, getDefaultVersion } = useHierarchy();
+  const { setCurrentPath, getVersionPath, getCurrentVersion, getCurrentNode, getDefaultVersion, getVersionMessage } = useHierarchy();
   const [isToggled, setSidebarOpen] = useState(false);
   const handleNavigate = () => setSidebarOpen(false);
   
   setCurrentPath(slug);
   const ver = getCurrentVersion();
   const currentNode = getCurrentNode();
+  const versionMessage = getVersionMessage();
 
   return (
     <>
@@ -37,7 +38,10 @@ const Layout: StatelessComponent<LayoutProps> = ({ children, pageContext: { slug
       <div className="docs-content">
         <div className="container">
           <article role="main" className="docs-article">
+            <>
+            {versionMessage}
             {children}
+            </>
           </article>
         </div> 
       </div>
diff --git a/src/components/NodeProvider.tsx b/src/components/NodeProvider.tsx
index 11f9469..a284125 100644
--- a/src/components/NodeProvider.tsx
+++ b/src/components/NodeProvider.tsx
@@ -15,6 +15,7 @@ import {
     getVersionPath,
     setCurrentPath,
     getDefaultVersion,
+    getVersionMessage,
 } from '../utils/nodes';
 
 const NodeProvider: StatelessComponent<{}> = ({ children, pageContext: { slug } }): ReactElement => {
@@ -61,6 +62,7 @@ const NodeProvider: StatelessComponent<{}> = ({ children, pageContext: { slug }
             getVersionPath,
             setCurrentPath,
             getDefaultVersion,
+            getVersionMessage,
         }}>
           {children}
       </NodeContext.Provider>
diff --git a/src/hooks/useHierarchy.ts b/src/hooks/useHierarchy.ts
index 4a4751b..2405bf9 100644
--- a/src/hooks/useHierarchy.ts
+++ b/src/hooks/useHierarchy.ts
@@ -1,4 +1,4 @@
-import { useContext } from 'react';
+import { useContext, ReactElement } from 'react';
 import NodeContext from '../contexts/NodeContext';
 import { SilverstripeDocument } from '../types';
 
@@ -15,6 +15,7 @@ interface NodeFunctions {
     getVersionPath(currentNode: SilverstripeDocument, version: number|string): string;
     setCurrentPath(slug: string): undefined;
     getDefaultVersion(): string;
+    getVersionMessage():  ReactElement | ReactElement[] | string | null;
 };
 
 const useHierarchy = (): NodeFunctions => {
diff --git a/src/theme/assets/scss/theme/_docs.scss b/src/theme/assets/scss/theme/_docs.scss
index 47da8a7..1374624 100644
--- a/src/theme/assets/scss/theme/_docs.scss
+++ b/src/theme/assets/scss/theme/_docs.scss
@@ -384,6 +384,60 @@
 	}
 }
 
+.callout-block--version {
+	border-left-width: 6px;
+	padding-top: 1rem;
+	padding-bottom: 1rem;
+	
+	.callout-version-title {
+		display: flex;
+		font-size: 1rem;
+		font-weight: $font-weight-bold;
+		color: lighten($theme-text-color-primary, 15%);
+
+		.callout-version-stability {
+			display: flex;
+			align-items: center;
+			margin-left: auto;
+			font-size: 1.125rem;
+		}
+
+		.callout-version-stability-text {
+			text-transform: uppercase;
+			font-size: 0.875rem;
+			margin-left: 10px;
+		}
+	}
+
+	.callout-version-content {
+		padding-top: 10px;
+	}
+
+	&.callout-block-success {
+		.callout-version-stability {
+			color: darken($theme-success-color, 15%);
+		}
+	}
+
+	&.callout-block-info {
+		.callout-version-stability {
+			color: darken($theme-info-color, 15%);
+		}
+	}
+
+	&.callout-block-warning {
+		.callout-version-stability {
+			color: darken($theme-warning-color, 15%);
+		}
+	}
+
+	&.callout-block-danger {
+		.callout-version-stability {
+			color: darken($theme-danger-color, 15%);
+		}
+	}
+}
+
 
 .cta-section {
 	.container {
diff --git a/src/utils/nodes.ts b/src/utils/nodes.ts
index 41aefa8..76b0ded 100644
--- a/src/utils/nodes.ts
+++ b/src/utils/nodes.ts
@@ -1,6 +1,7 @@
+import parse from 'html-react-parser';
+import { ReactElement } from 'react';
 import { SilverstripeDocument } from '../types';
 import sortFiles from './sortFiles';
-import { node } from 'prop-types';
 
 let __nodes: SilverstripeDocument[];
 let __currentVersion: string | null = null;
@@ -149,17 +150,65 @@ const getDefaultVersion = (): string => '4';
  */
 const getCurrentVersion = (): string => __currentVersion || getDefaultVersion();
 
+/**
+ * Get a message to display for all pages on this version's docs
+ */
+const getVersionMessage = (): ReactElement | ReactElement[] | string | null => {
+  const EOL = [
+    '3',
+  ];
+  const PRE_RELEASE = [
+    '5',
+  ];
+  const version = getCurrentVersion();
+  const stablePath = getVersionPath(getCurrentNode(), getDefaultVersion());
+
+  // Output the appropriate message and styling
+  function makeMessage(style: string, icon: string, stability: string, message: string|null): string {
+    let template = `<div id="version-callout" class="callout-block callout-block--version callout-block-${style}">
+      <div class="callout-version-title">Version ${version}<span class="callout-version-stability">
+        <i class="far fa-${icon}"></i><span class="callout-version-stability-text">${stability}</span></span>
+      </div>`;
+    if (message) {
+      template += `<div class="callout-version-content">
+          This version of Silverstripe CMS ${message}.
+          <a href="${stablePath}">Go to documentation for the most recent stable version.</a>
+        </div>`;
+    }
+    template += '</div>';
+    return template;
+  }
+
+  // Return the correct message for the current version
+  if (EOL.includes(version)) {
+    return parse(makeMessage('danger', 'times-circle', 'end of life', 'will not recieve any additional bug fixes or documentation updates'));
+  }
+  if (PRE_RELEASE.includes(version)) {
+    return parse(makeMessage(
+      'warning',
+      'calendar',
+      'pre-stable',
+      'has not yet been given a stable release. See <a target="_blank" href="https://www.silverstripe.org/software/roadmap/">the release roadmap</a> for more information'
+    ));
+  }
+  return parse(makeMessage('success', 'check-circle', 'supported', null));
+};
+
 
 /**
  * Gets the path in another version
  * @param currentNode 
  * @param version 
  */
-const getVersionPath = (currentNode: SilverstripeDocument, version: number): string => {
-  const newPath = currentNode.slug.replace(/^\/en\/[0-9]+\//, `/en/${version}/`);
+const getVersionPath = (currentNode: SilverstripeDocument|null, version: number|string): string => {
+  const basePath = `/en/${version}`;
+  if (!currentNode) {
+    return basePath;
+  }
+  const newPath = currentNode.slug.replace(/^\/en\/[0-9]+\//, `${basePath}/`);
   const otherNode = getNodes().find(n => n.slug === newPath);
 
-  return otherNode ? otherNode.slug : `/en/${version}`;
+  return otherNode ? otherNode.slug : basePath;
 };
 
 /**
@@ -185,4 +234,5 @@ export {
   getVersionPath,
   setCurrentPath,
   getDefaultVersion,
+  getVersionMessage,
 };
\ No newline at end of file
diff --git a/src/utils/rewriteHeader.ts b/src/utils/rewriteHeader.ts
index f3e67f0..0b7cf4f 100644
--- a/src/utils/rewriteHeader.ts
+++ b/src/utils/rewriteHeader.ts
@@ -65,6 +65,13 @@ const rewriteHeaders = (domNode: DomElement): ReactElement | false => {
 
         domNode.children?.push(anchor);
 
+        if (domNode.name === 'h1') {
+            if (!domNode.attribs) {
+                domNode.attribs = {};
+            }
+            domNode.attribs['aria-details'] = 'version-callout';
+        }
+
         return domToReact([domNode]);
 
     }