fix(SSR): explicitly load KtNavbar as a component

A change in the template of NavBar.vue produced a very hard to trace down bug
which caused the navbar to not render in the documentation. Although the source
of this bug could not be made out, it seemed to have to do with how nuxt is
resolving components. Adding an explicit import of KtNavbar in the file (and
therefore not relying on the kotti-ui plugin for nuxt) fixes this.

As the file change that triggered this is very unrelated and it would be impossible
to see this very unrelated effect in code review, a test was added that should at
least stop the very same event to occur

Co-Authored-By: Florian Wendelborn <[email protected]>

packages/documentation/components/NavBar.vue

@@ -15,6 +15,7 @@
 
 <script lang="ts">
 import type { Kotti } from '@3yourmind/kotti-ui'
+import { KtNavbar } from '@3yourmind/kotti-ui'
 import { computed, defineComponent, ref } from 'vue'
 
 import navLogo from '../assets/img/nav_logo.svg'
@@ -38,6 +39,9 @@ const saveSavedFieldsToLocalStorage = (isNarrow: boolean) => {
 
 export default defineComponent({
 	name: 'NavBar',
+	components: {
+		KtNavbar,
+	},
 	setup() {
 		const route = useRoute()
 

packages/documentation/package.json

@@ -41,7 +41,7 @@
 	},
 	"private": true,
 	"scripts": {
-		"build": "nuxt generate",
+		"build": "nuxt generate && ./scripts/test-for-ssr-bug.sh",
 		"check:eslint": "eslint --max-warnings=0 .",
 		"check:prettier": "yarn --cwd ../.. run prettier --check --ignore-path=.gitignore ./packages/documentation",
 		"check:stylelint": "stylelint './**/*.{css,scss,vue}'",

packages/documentation/scripts/test-for-ssr-bug.sh

@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+# What happened to make this test necessary?
+#
+# Beginning of June 2024 the documentation page had a peculiar bug: The main Navbar did not render.
+#
+# What was the cause of that bug?
+#
+# The bug was traced down to a change (that seemed entirely unrelated) in documentation/components/NavBar.vue
+# Closer investigation yielded that this change had an unintended effect on how nuxt is resolving imports
+# when it is rendering/hydrating components.
+#
+# How was this solved
+#
+# The fix was to make nuxt explictly resolve the component during SSR. This causes the following change to
+# index.html that is generated by `nuxt generate`:
+#
+# -  <ktnavbar class="kt-navbar">...</ktnavbar>  <!-- Will be hydrated client side -->
+#
+# +  <nav class="kt-navbar">...</nav> <!-- pre-rendered server-side -->
+#
+# Why this test?
+#
+# Since this was impossible to foresee and would likely slip through a code review in a possible future scenario
+# this is a very basic sanity test to at least catch the very same scenario.
+
+if grep '</ktnavbar>' ./dist/index.html;
+then echo "The output of nuxt contains a 'ktnavbar' tag, this might be the result of a strange SSR bug" && false;
+else true;
+fi

packages/kotti-ui/source/kotti-navbar/KtNavbar.vue

@@ -93,6 +93,7 @@ export default defineComponent({
 		watch(
 			() => props.theme,
 			(newTheme) => {
+				if (typeof document === 'undefined') return // SSR
 				const rootElement = document.querySelector(':root') as HTMLElement
 
 				rootElement.style.setProperty(