docs: add version banner

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>

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;
+}

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;

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
+    );
+  },
+};

docs/.vitepress/tsconfig.json

@@ -1,6 +1,7 @@
 {
   "compilerOptions": {
     "target": "ES2020",
+    "module": "ES2020",
     "moduleResolution": "Node",
     "resolveJsonModule": true
   }

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 = [
   {

package.json

@@ -107,6 +107,7 @@
     "@typescript-eslint/parser": "~5.40.1",
     "@vitest/coverage-c8": "~0.24.3",
     "@vitest/ui": "~0.24.3",
+    "@vueuse/core": "~9.4.0",
     "c8": "~7.12.0",
     "conventional-changelog-cli": "~2.2.2",
     "cypress": "~10.10.0",
@@ -137,8 +138,9 @@
     "typescript": "~4.8.4",
     "validator": "~13.7.0",
     "vite": "~3.1.8",
-    "vitepress": "1.0.0-alpha.22",
-    "vitest": "~0.24.3"
+    "vitepress": "1.0.0-alpha.26",
+    "vitest": "~0.24.3",
+    "vue": "~3.2.41"
   },
   "packageManager": "pnpm@7.14.0",
   "engines": {