feat(plugin-theme-data): extract theme data injection to a plugin

Author: meteorlxy

docs/.vuepress/configs/sidebar/en.ts

@@ -84,6 +84,7 @@ export const en: SidebarConfig = {
         '/reference/plugin/palette-stylus.md',
         '/reference/plugin/pwa.md',
         '/reference/plugin/pwa-popup.md',
+        '/reference/plugin/theme-data.md',
       ],
     },
   ],

docs/.vuepress/configs/sidebar/zh.ts

@@ -87,6 +87,7 @@ export const zh: SidebarConfig = {
         '/zh/reference/plugin/palette-stylus.md',
         '/zh/reference/plugin/pwa.md',
         '/zh/reference/plugin/pwa-popup.md',
+        '/zh/reference/plugin/theme-data.md',
       ],
     },
   ],

docs/reference/plugin/theme-data.md

@@ -0,0 +1,103 @@
+# theme-data
+
+> @vuepress/plugin-theme-data
+
+Provide client data for your theme, with VuePress [i18n](../../guide/i18n.md) support.
+
+This plugin is mainly used to develop themes, and has been integrated into the default theme. You won't need to use it directly in most cases.
+
+For theme authors, this plugin will help you to use the same i18n mechanism as VuePress and the default theme. But if you don't want to provide i18n support, or you want to implement in your own way, you don't need this plugin.
+
+## Options
+
+### themeData
+
+- Type: `ThemeData`
+
+- Default: `{}`
+
+- Details:
+
+  The theme data object that you want to use in client side.
+
+  You can provide theme data in Node side via this option, and use it in client side via [useThemeData](#useThemeData) and [useThemeLocaleData](#useThemeLocaleData).
+
+- Example:
+
+```js
+module.exports = {
+  plugins: [
+    [
+      '@vuepress/plugin-theme-data',
+      {
+        themeData: {
+          foo: 'foo',
+          locales: {
+            '/zh/': {
+              foo: 'zh-foo',
+            },
+          },
+        },
+      },
+    ],
+  ],
+}
+```
+
+::: warning
+The theme data object will be processed by `JSON.stringify()` before forwarding to client side, so you should ensure that you are providing a JSON-friendly object.
+:::
+
+## Composition API
+
+### useThemeData
+
+- Details:
+
+  Returns the theme data ref object.
+  
+  The value is provided by [themeData](#themeData) option.
+
+- Example:
+
+```ts
+import { useThemeData } from '@vuepress/plugin-theme-data/lib/composables'
+import type { ThemeData } from '@vuepress/plugin-theme-data'
+
+type MyThemeData = ThemeData<{
+  foo: string
+}>
+
+export default {
+  setup() {
+    const themeData = useThemeData<MyThemeData>()
+    console.log(themeData.value)
+  },
+}
+```
+
+### useThemeLocaleData
+
+- Details:
+
+  Returns the theme data ref object in current locale.
+
+  The values of current locale has been merged into the root-level.
+
+- Example:
+
+```ts
+import { useThemeLocaleData } from '@vuepress/plugin-theme-data/lib/composables'
+import type { ThemeData } from '@vuepress/plugin-theme-data'
+
+type MyThemeData = ThemeData<{
+  foo: string
+}>
+
+export default {
+  setup() {
+    const themeLocaleData = useThemeLocaleData<MyThemeData>()
+    console.log(themeLocaleData.value)
+  },
+}
+```

docs/zh/reference/plugin/theme-data.md

@@ -0,0 +1,103 @@
+# theme-data
+
+> @vuepress/plugin-theme-data
+
+为你主题提供客户端数据，包含 VuePress 的 [多语言支持](../../guide/i18n.md) 。
+
+该插件主要用于开发主题，并且已经集成到默认主题中。大部分情况下你不需要直接使用它。
+
+对于主题作者，该插件可以提供与 VuePress 及默认主题相同的多语言支持机制。但是如果你的主题不需要提供多语言支持，或者你想用你自己的方式来实现多语言支持，那么你不需要使用该插件。
+
+## 配置项
+
+### themeData
+
+- 类型： `ThemeData`
+
+- 默认值： `{}`
+
+- 详情：
+
+  你希望在 Client 端中使用的主题数据对象。
+
+  你可以通过该配置项，在 Node 端提供主题数据，然后在客户端通过 [useThemeData](#useThemeData) 和 [useThemeLocaleData](#useThemeLocaleData) 来使用主题数据。
+
+- 示例：
+
+```js
+module.exports = {
+  plugins: [
+    [
+      '@vuepress/plugin-theme-data',
+      {
+        themeData: {
+          foo: 'foo',
+          locales: {
+            '/zh/': {
+              foo: 'zh-foo',
+            },
+          },
+        },
+      },
+    ],
+  ],
+}
+```
+
+::: warning
+主题数据对象在传递到客户端之前，会使用 `JSON.stringify()` 进行处理，因此你需要保证你提供的是一个可以被 JSON 序列化的对象。
+:::
+
+## Composition API
+
+### useThemeData
+
+- 详情：
+
+  返回主题数据的 Ref 对象。
+  
+  数据是通过 [themeData](#themeData) 配置项提供的。
+
+- 示例：
+
+```ts
+import { useThemeData } from '@vuepress/plugin-theme-data/lib/composables'
+import type { ThemeData } from '@vuepress/plugin-theme-data'
+
+type MyThemeData = ThemeData<{
+  foo: string
+}>
+
+export default {
+  setup() {
+    const themeData = useThemeData<MyThemeData>()
+    console.log(themeData.value)
+  },
+}
+```
+
+### useThemeLocaleData
+
+- 详情：
+
+  返回当前 locale 下主题数据的 Ref 对象。
+
+  当前 locale 中的字段已被合并到顶层字段中。
+
+- 示例：
+
+```ts
+import { useThemeLocaleData } from '@vuepress/plugin-theme-data/lib/composables'
+import type { ThemeData } from '@vuepress/plugin-theme-data'
+
+type MyThemeData = ThemeData<{
+  foo: string
+}>
+
+export default {
+  setup() {
+    const themeLocaleData = useThemeLocaleData<MyThemeData>()
+    console.log(themeLocaleData.value)
+  },
+}
+```

packages/@vuepress/plugin-theme-data/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@vuepress/plugin-theme-data",
+  "version": "2.0.0-alpha.24",
+  "description": "VuePress plugin - theme data",
+  "keywords": [
+    "vuepress-plugin",
+    "vuepress",
+    "plugin",
+    "theme"
+  ],
+  "homepage": "https://github.com/vuepress",
+  "bugs": {
+    "url": "https://github.com/vuepress/vuepress-next/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vuepress/vuepress-next.git"
+  },
+  "license": "MIT",
+  "author": "meteorlxy",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "files": [
+    "lib"
+  ],
+  "scripts": {
+    "build": "tsc -b tsconfig.build.json",
+    "clean": "rimraf lib *.tsbuildinfo"
+  },
+  "dependencies": {
+    "@vuepress/client": "2.0.0-alpha.24",
+    "@vuepress/core": "2.0.0-alpha.24",
+    "@vuepress/shared": "2.0.0-alpha.24",
+    "@vuepress/utils": "2.0.0-alpha.24"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

packages/@vuepress/plugin-theme-data/src/clientAppEnhance.ts

@@ -0,0 +1,34 @@
+import { computed } from 'vue'
+import { routeLocaleSymbol } from '@vuepress/client'
+import type { ClientAppEnhance } from '@vuepress/client'
+import {
+  useThemeData,
+  resolveThemeLocaleData,
+  themeLocaleDataSymbol,
+} from './composables'
+
+const clientAppEnhance: ClientAppEnhance = ({ app }) => {
+  // provide theme data & theme locale data
+  const themeData = useThemeData()
+  const routeLocale =
+    app._context.provides[(routeLocaleSymbol as unknown) as string]
+  const themeLocaleData = computed(() =>
+    resolveThemeLocaleData(themeData.value, routeLocale.value)
+  )
+  app.provide(themeLocaleDataSymbol, themeLocaleData)
+
+  Object.defineProperties(app.config.globalProperties, {
+    $theme: {
+      get() {
+        return themeData.value
+      },
+    },
+    $themeLocale: {
+      get() {
+        return themeLocaleData.value
+      },
+    },
+  })
+}
+
+export default clientAppEnhance

packages/@vuepress/plugin-theme-data/src/composables/index.ts

@@ -0,0 +1,2 @@
+export * from './useThemeData'
+export * from './useThemeLocaleData'

packages/@vuepress/plugin-theme-data/src/composables/useThemeData.ts

@@ -0,0 +1,19 @@
+import { readonly, ref } from 'vue'
+import type { Ref } from 'vue'
+import { themeData as themeDataRaw } from '@internal/themeData'
+import type { ThemeData } from '../types'
+
+export type ThemeDataRef<T extends ThemeData = ThemeData> = Ref<T>
+
+export const themeData: ThemeDataRef = ref(readonly(themeDataRaw) as ThemeData)
+
+export const useThemeData = <
+  T extends ThemeData = ThemeData
+>(): ThemeDataRef<T> => themeData as ThemeDataRef<T>
+
+if (import.meta.webpackHot) {
+  import.meta.webpackHot!.accept('@internal/themeData', () => {
+    themeData.value = readonly(themeDataRaw) as ThemeData
+    console.log('[vuepress] themeData is updated')
+  })
+}

packages/@vuepress/plugin-theme-data/src/composables/useThemeLocaleData.ts

@@ -0,0 +1,34 @@
+import { inject } from 'vue'
+import type { ComputedRef, InjectionKey } from 'vue'
+import type { RouteLocale } from '@vuepress/client'
+import type { ThemeData } from '../types'
+
+declare const __DEV__: boolean
+
+export type ThemeLocaleDataRef<T extends ThemeData = ThemeData> = ComputedRef<T>
+
+export const themeLocaleDataSymbol: InjectionKey<ThemeLocaleDataRef> = Symbol(
+  __DEV__ ? 'themeLocaleData' : ''
+)
+
+export const useThemeLocaleData = <
+  T extends ThemeData = ThemeData
+>(): ThemeLocaleDataRef<T> => {
+  const themeLocaleData = inject(themeLocaleDataSymbol)
+  if (!themeLocaleData) {
+    throw new Error('useThemeLocaleData() is called without provider.')
+  }
+  return themeLocaleData as ThemeLocaleDataRef<T>
+}
+
+/**
+ * Merge the locales fields to the root fields
+ * according to the route path
+ */
+export const resolveThemeLocaleData = (
+  theme: ThemeData,
+  routeLocale: RouteLocale
+): ThemeData => ({
+  ...theme,
+  ...theme.locales?.[routeLocale],
+})

packages/@vuepress/plugin-theme-data/src/index.ts

@@ -0,0 +1,33 @@
+import type { Plugin } from '@vuepress/core'
+import { path } from '@vuepress/utils'
+import type { ThemeData } from './types'
+
+export type { ThemeData }
+
+/**
+ * Options of @vuepress/plugin-theme-data
+ */
+export interface ThemeDataPluginOptions {
+  /**
+   * Theme data to be used in client side
+   */
+  themeData?: ThemeData
+}
+
+export const themeDataPlugin: Plugin<ThemeDataPluginOptions> = ({
+  themeData = {},
+}) => ({
+  name: '@vuepress/plugin-theme-data',
+
+  clientAppEnhanceFiles: path.resolve(__dirname, './clientAppEnhance.js'),
+
+  onPrepared: async (app) => {
+    const content = `\
+  export const themeData = ${JSON.stringify(themeData, null, 2)}
+  `
+
+    await app.writeTemp('internal/themeData.js', content)
+  },
+})
+
+export default themeDataPlugin