docs: add version banner (#1487)

6 files changed, 175 insertions, 3 deletions

diff --git a/docs/.vitepress/components/Banner.vue b/docs/.vitepress/components/Banner.vue
new file mode 100644
index 00000000..9eea81c9
--- /dev/null
+++ b/docs/.vitepress/components/Banner.vue
@@ -0,0 +1,108 @@
+<script setup lang="ts">
+import { useElementSize } from '@vueuse/core';
+import { ref, watchEffect } from 'vue';
+
+defineProps<{
+  version: string;
+}>();
+
+const el = ref<HTMLElement>();
+const { height } = useElementSize(el);
+
+watchEffect(() => {
+  if (height.value) {
+    document.documentElement.style.setProperty(
+      '--vp-layout-top-height',
+      `${height.value + 16}px`
+    );
+  }
+});
+
+const dismiss = () => {
+  localStorage.setItem(
+    'faker-version-banner',
+    (Date.now() + 8.64e7 * 1).toString() // current time + 1 day
+  );
+  document.documentElement.classList.add('banner-dismissed');
+};
+</script>
+
+<template>
+  <div ref="el" class="banner">
+    <div class="text">
+      These docs are of {{ version }}. For docs of the current version visit:
+      <a href="https://fakerjs.dev/">fakerjs.dev</a>
+    </div>
+
+    <button type="button" @click="dismiss">
+      <svg
+        xmlns="http://www.w3.org/2000/svg"
+        viewBox="0 0 20 20"
+        fill="currentColor"
+      >
+        <path
+          d="M6.28 5.22a.75.75 0 00-1.06 1.06L8.94 10l-3.72 3.72a.75.75 0 101.06 1.06L10 11.06l3.72 3.72a.75.75 0 101.06-1.06L11.06 10l3.72-3.72a.75.75 0 00-1.06-1.06L10 8.94 6.28 5.22z"
+        />
+      </svg>
+    </button>
+  </div>
+</template>
+
+<style>
+.banner-dismissed {
+  --vp-layout-top-height: 0px !important;
+}
+
+html {
+  --vp-layout-top-height: 88px;
+}
+
+@media (min-width: 375px) {
+  html {
+    --vp-layout-top-height: 64px;
+  }
+}
+
+@media (min-width: 768px) {
+  html {
+    --vp-layout-top-height: 40px;
+  }
+}
+</style>
+
+<style scoped>
+.banner-dismissed .banner {
+  display: none;
+}
+
+.banner {
+  position: fixed;
+  top: 0;
+  right: 0;
+  left: 0;
+  z-index: var(--vp-z-index-layout-top);
+
+  padding: 8px;
+  text-align: center;
+
+  background: #383636;
+  color: #fff;
+
+  display: flex;
+  justify-content: space-between;
+}
+
+.text {
+  flex: 1;
+}
+
+a {
+  text-decoration: underline;
+}
+
+svg {
+  width: 20px;
+  height: 20px;
+  margin-left: 8px;
+}
+</style>
diff --git a/docs/.vitepress/components/shims.d.ts b/docs/.vitepress/components/shims.d.ts
new file mode 100644
index 00000000..7ae275ab
--- /dev/null
+++ b/docs/.vitepress/components/shims.d.ts
@@ -0,0 +1,7 @@
+declare const __BANNER__: string | false;
+
+declare module '*.vue' {
+  import type { DefineComponent } from 'vue';
+  const component: DefineComponent;
+  export default component;
+}
diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts
index 1191ddd1..aa0045d8 100644
--- a/docs/.vitepress/config.ts
+++ b/docs/.vitepress/config.ts
@@ -1,7 +1,7 @@
 import { defineConfig } from 'vitepress';
 import { DefaultTheme } from 'vitepress/theme';
 import { apiPages } from './api-pages';
-import { currentVersion, oldVersions } from './versions';
+import { currentVersion, oldVersions, versionBannerInfix } from './versions';
 
 type SidebarGroup = DefaultTheme.SidebarGroup;
 
@@ -51,7 +51,7 @@ function extendSideNav(current: SidebarGroup): SidebarGroup[] {
   return links;
 }
 
-export default defineConfig({
+const config = defineConfig({
   title: 'Faker',
   description,
 
@@ -229,4 +229,29 @@ export default defineConfig({
       }),
     },
   },
+
+  vite: {
+    define: {
+      __BANNER__: versionBannerInfix ?? false,
+    },
+  },
 });
+
+if (versionBannerInfix) {
+  config.head?.push([
+    'script',
+    { id: 'restore-banner-preference' },
+    `
+(() => {
+  const restore = (key, cls, def = false) => {
+    const saved = localStorage.getItem(key);
+    if (saved ? saved !== 'false' && new Date() < saved : def) {
+      document.documentElement.classList.add(cls);
+    }
+  };
+  restore('faker-version-banner', 'banner-dismissed');
+})();`,
+  ]);
+}
+
+export default config;
diff --git a/docs/.vitepress/theme/index.ts b/docs/.vitepress/theme/index.ts
index 2423da6b..8555a839 100644
--- a/docs/.vitepress/theme/index.ts
+++ b/docs/.vitepress/theme/index.ts
@@ -1,4 +1,22 @@
 import DefaultTheme from 'vitepress/theme';
+import { defineAsyncComponent, h } from 'vue';
 import './index.css';
 
-export default DefaultTheme;
+export default {
+  ...DefaultTheme,
+  Layout() {
+    return h(
+      DefaultTheme.Layout,
+      null,
+      __BANNER__
+        ? {
+            'layout-top': () =>
+              h(
+                defineAsyncComponent(() => import('../components/Banner.vue')),
+                { version: __BANNER__ }
+              ),
+          }
+        : null
+    );
+  },
+};
diff --git a/docs/.vitepress/tsconfig.json b/docs/.vitepress/tsconfig.json
index 74d4053a..75b15f9e 100644
--- a/docs/.vitepress/tsconfig.json
+++ b/docs/.vitepress/tsconfig.json
@@ -1,6 +1,7 @@
 {
   "compilerOptions": {
     "target": "ES2020",
+    "module": "ES2020",
     "moduleResolution": "Node",
     "resolveJsonModule": true
   }
diff --git a/docs/.vitepress/versions.ts b/docs/.vitepress/versions.ts
index 7d37619d..2964557c 100644
--- a/docs/.vitepress/versions.ts
+++ b/docs/.vitepress/versions.ts
@@ -41,6 +41,19 @@ const hiddenLink =
 const otherVersions = readOtherLatestReleaseTagNames();
 const isReleaseBranch = /^v\d+$/.test(branchName);
 
+export const versionBannerInfix: string | null = (() => {
+  if (deployContext === 'production') {
+    return null;
+  }
+  if (isReleaseBranch) {
+    return '"an old version"';
+  }
+  if (branchName === 'next') {
+    return '"the next (unreleased) version"';
+  }
+  return '"a development version"';
+})();
+
 export const currentVersion = isReleaseBranch ? `v${version}` : branchName;
 export const oldVersions = [
   {