fix(web): Fix browser back navigation

Back navigation trough pages showing the "lastest" version,
when the version is for example called v1.0.1,
by splitting version and displayVersion in the code

Author: tbuerli-komax

web/src/components/DocumentControlButtons.tsx

@@ -19,6 +19,7 @@ interface Props {
   version: string
   versions: ProjectDetails[]
   onVersionChange: (version: string) => void
+  getShareUrl: (options: { useLatest: boolean, hideUi: boolean }) => string
 }
 
 export default function DocumentControlButtons(props: Props): React.JSX.Element {
@@ -31,25 +32,6 @@ export default function DocumentControlButtons(props: Props): React.JSX.Element
   // Cannot copy when page is served over HTTP
   const canCopy = navigator.clipboard !== undefined
 
-  const getShareUrl = (): string => {
-    // adapt the current URL so we can leave Docs.tsx's state as refs
-    // (which means if the page was passed down as a prop it wouldn't update correctly)
-
-    let url = window.location.href
-
-    if (shareModalUseLatest) {
-      url = url.replace(props.version, 'latest')
-    }
-
-    if (shareModalHideUi) {
-      const urlObject = new URL(url)
-      urlObject.search = 'hide-ui'
-      url = urlObject.toString()
-    }
-
-    return url
-  }
-
   return (
     <div className={styles.controls}>
       <Tooltip title="Docs Overview" placement="top" arrow>
@@ -111,14 +93,14 @@ export default function DocumentControlButtons(props: Props): React.JSX.Element
       >
         <div className={styles['share-modal']}>
           <div className={styles['share-modal-link-container']}>
-            <p className={styles['share-modal-link']}>{getShareUrl()}</p>
+            <p className={styles['share-modal-link']}>{props.getShareUrl({ useLatest: shareModalUseLatest, hideUi: shareModalHideUi })}</p>
             {canCopy && (
               <div className={styles['share-modal-copy-container']}>
                 <button
                   className={styles['share-modal-copy']}
                   onClick={() => {
                     void (async () => {
-                      await navigator.clipboard.writeText(getShareUrl())
+                      await navigator.clipboard.writeText(props.getShareUrl({ useLatest: shareModalUseLatest, hideUi: shareModalHideUi }))
                     })()
                   }}
                 >

web/src/pages/Docs.tsx

@@ -7,22 +7,22 @@ import DocumentControlButtons from '../components/DocumentControlButtons'
 import IFrame from '../components/IFrame'
 import { useLocation, useParams, useSearchParams } from 'react-router-dom'
 import { useMessageBanner } from '../data-providers/MessageBannerProvider'
-import IframeNotFound from './IframePageNotFound'
 
 export default function Docs(): JSX.Element {
   const params = useParams()
   const [searchParams] = useSearchParams()
   const location = useLocation()
   const { showMessage, clearMessages } = useMessageBanner()
 
-  const [iframePageNotFound, setIframePageNotFound] = useState<boolean>(false)
   const [versions, setVersions] = useState<ProjectDetails[]>([])
-  const [loadingFailed, setLoadingFailed] = useState<boolean>(false)
+  const [displayVersion, setDisplayVersion] = useState<ProjectDetails | null>(null)
+  const [projectLoading, setProjectLoading] = useState<boolean>(true)
+  const [notFound, setNotFound] = useState<boolean>(false)
 
-  const project = useRef(params.project ?? '')
   const page = useRef(params['*'] ?? '')
   const hash = useRef(location.hash)
 
+  const [project, setProject] = useState<string>(params.project ?? '')
   const [version, setVersion] = useState<string>(params.version ?? 'latest')
   const [hideUi, setHideUi] = useState<boolean>(searchParams.get('hide-ui') === '' || searchParams.get('hide-ui') === 'true')
   const [iframeUpdateTrigger, setIframeUpdateTrigger] = useState<number>(0)
@@ -33,97 +33,83 @@ export default function Docs(): JSX.Element {
   // is not needed when only the page or hash changes, because
   // the iframe keeps track of that itself.
   const iFrameSrc = useMemo(() => {
+    if (!displayVersion) {
+      return ''
+    }
     return ProjectRepository.getProjectDocsURL(
-      project.current,
-      version,
+      project,
+      displayVersion.name,
       page.current,
       hash.current
     )
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [version, iframeUpdateTrigger])
+  }, [project, displayVersion, iframeUpdateTrigger])
 
   useEffect(() => {
-    if (project.current === '') {
-      return
-    }
-
-    void (async (): Promise<void> => {
+    setProjectLoading(true)
+    const loadProject = async () => {
       try {
-        let allVersions = await ProjectRepository.getVersions(project.current)
-        if (allVersions.length === 0) {
-          setLoadingFailed(true)
-          return
-        }
-
+        let allVersions = await ProjectRepository.getVersions(project)
         allVersions = allVersions.sort((a, b) =>
           ProjectRepository.compareVersions(a, b)
         )
         setVersions(allVersions)
-
-        const latestVersion =
-          ProjectRepository.getLatestVersion(allVersions).name
-        if (version === 'latest') {
-          if (latestVersion === 'latest') {
-            return
-          }
-          setVersion(latestVersion)
-          return
-        }
-
-        // custom version -> check if it exists
-        // if it does. do nothing, as it should be set already
-        const versionsAndTags = allVersions
-          .map((v) => [v.name, ...v.tags])
-          .flat()
-        if (versionsAndTags.includes(version)) {
-          return
-        }
-
-        // version does not exist -> fail
-        setLoadingFailed(true)
-        console.error(`Version '${version}' doesn't exist`)
       } catch (e) {
         console.error(e)
-        setLoadingFailed(true)
       }
-    })()
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [project])
+    }
+    loadProject().finally(() => {
+      setProjectLoading(false)
+    })
+  }, [project]);
 
-  /** Encodes the url for the current page.
-   * @example
-   * getUrl('project', 'version', 'path/to/page.html', '#hash', false) -> '/project/version/path/to/page.html#hash'
-   */
-  const getUrl = (
-    project: string,
-    version: string,
-    page: string,
-    hash: string,
-    hideUi: boolean
-  ): string => {
-    return `/${project}/${version}/${encodeURI(page)}${hash}${hideUi ? '?hide-ui' : ''}`
+  const buildBrowserUrl = (project: string, version: string, page: string, hash: string, hideUi: boolean): string => {
+    return `/${project}/${version}/${page}${hideUi ? '?hide-ui' : ''}${hash}`
   }
 
-  const updateUrl = (newVersion: string, hideUi: boolean): void => {
-    const url = getUrl(
-      project.current,
-      newVersion,
-      page.current,
-      hash.current,
-      hideUi
-    )
-    window.history.pushState(null, '', url)
+  const getShareUrl = (options: { useLatest: boolean, hideUi: boolean }): string => {
+    return buildBrowserUrl(project, options.useLatest ? 'latest' : displayVersion?.name ?? 'latest', page.current, hash.current, options.hideUi)
   }
 
-  const updateTitle = (newTitle: string): void => {
-    document.title = newTitle
+  const updateUrl = (newProject: string, newVersion: string, hideUi: boolean): void => {
+    window.history.pushState(null, '', buildBrowserUrl(newProject, newVersion, page.current, hash.current, hideUi))
   }
 
-  // Keep compatibility with encoded page path
   useEffect(() => {
-    updateUrl(version, hideUi)
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [])
+    if (versions.length === 0) {
+      return
+    }
+
+    if (version === 'latest') {
+      const latestVersion = ProjectRepository.getLatestVersion(versions)
+      setDisplayVersion(latestVersion)
+    } else {
+      const matchingVersion = versions.find((v) => v.name === version || v.tags.includes(version))
+      if (matchingVersion) {
+        setDisplayVersion(matchingVersion)
+      } else {
+        setNotFound(true)
+        console.error(`Version '${version}' doesn't exist`)
+      }
+    }
+  }, [versions, version])
+
+  useEffect(() => {
+    const latestVersion = ProjectRepository.getLatestVersion(versions)
+    if (displayVersion === latestVersion) {
+      clearMessages()
+    } else {
+      showMessage({
+        content: 'You are viewing an outdated version of the documentation.',
+        type: 'warning',
+        showMs: null
+      })
+    }
+  }, [displayVersion, versions, showMessage, clearMessages])
+
+  const updateTitle = (newTitle: string): void => {
+    document.title = newTitle
+  }
 
   const iFramePageChanged = (urlPage: string, urlHash: string, title?: string): void => {
     if (title != null && title !== document.title) {
@@ -134,19 +120,19 @@ export default function Docs(): JSX.Element {
     }
     page.current = urlPage
     hash.current = urlHash
-    updateUrl(version, hideUi)
+    updateUrl(project, version, hideUi)
   }
 
   const iFrameHashChanged = (newHash: string): void => {
     if (newHash === hash.current) {
       return
     }
     hash.current = newHash
-    updateUrl(version, hideUi)
+    updateUrl(project, version, hideUi)
   }
 
   const iFrameNotFound = (): void => {
-    setIframePageNotFound(true)
+    setNotFound(true)
   }
 
   const iFrameFaviconChanged = (faviconUrl: string | null): void => {
@@ -157,34 +143,18 @@ export default function Docs(): JSX.Element {
     favicon.href = faviconUrl
   }
 
-  const onVersionChanged = (newVersion: string): void => {
-    if (newVersion === version) {
-      return
-    }
-    setVersion(newVersion)
-    updateUrl(newVersion, hideUi)
-  }
-
   useEffect(() => {
     const urlProject = params.project ?? ''
     const urlVersion = params.version ?? 'latest'
     const urlPage = params['*'] ?? ''
     const urlHash = location.hash
     const urlHideUi = searchParams.get('hide-ui') === '' || searchParams.get('hide-ui') === 'true'
 
-    // update the state to the url params on first loadon
-    if (urlProject !== project.current) {
-      setVersions([])
-      project.current = urlProject
-    }
-
-    if (urlVersion !== version) {
-      setVersion(urlVersion)
-    }
-
-    if (urlHideUi !== hideUi) {
-      setHideUi(urlHideUi)
-    }
+    // update the state to the url params on first load
+    setNotFound(false)
+    setProject(urlProject)
+    setVersion(urlVersion)
+    setHideUi(urlHideUi)
 
     if (urlPage !== page.current) {
       page.current = urlPage
@@ -194,48 +164,15 @@ export default function Docs(): JSX.Element {
       hash.current = urlHash
       setIframeUpdateTrigger((v) => v + 1)
     }
-
-    setIframePageNotFound(false)
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [location])
 
-  useEffect(() => {
-    // check every time the version changes whether the version
-    // is the latest version and if not, show a banner
-    if (versions.length === 0) {
-      return
-    }
-
-    const latestVersion = ProjectRepository.getLatestVersion(versions).name
-    if (version === latestVersion) {
-      clearMessages()
-      return
-    }
-
-    showMessage({
-      content: 'You are viewing an outdated version of the documentation.',
-      type: 'warning',
-      showMs: null
-    })
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [version, versions])
-
-  if (loadingFailed || project.current === '') {
-    return <NotFound />
-  }
-
-  if (iframePageNotFound) {
-    return (
-      <IframeNotFound
-        project={project.current}
-        version={version}
-        hideUi={hideUi}
-      />
-    )
+  if (projectLoading) {
+    return <LoadingPage />
   }
 
-  if (versions.length === 0) {
-    return <LoadingPage />
+  if (displayVersion == null || notFound) {
+    return <NotFound />
   }
 
   return (
@@ -250,9 +187,13 @@ export default function Docs(): JSX.Element {
       />
       {!hideUi && (
         <DocumentControlButtons
-          version={version}
+          version={displayVersion.name}
           versions={versions}
-          onVersionChange={onVersionChanged}
+          onVersionChange={(newVersion) => {
+            updateUrl(project, newVersion, hideUi)
+            setVersion(newVersion)
+          }}
+          getShareUrl={getShareUrl}
         />
       )}
     </>