feat(client)!: shorten data keys

Author: Mister-Hope

e2e/docs/.vuepress/theme/client/layouts/Layout.vue

@@ -1,15 +1,13 @@
 <script setup lang="ts">
-import { Content, useSiteData } from 'vuepress/client'
-
-const siteData = useSiteData()
+import { Content } from 'vuepress/client'
 </script>
 
 <template>
   <div class="e2e-theme">
     <nav class="e2e-theme-nav">
       <div>Languages</div>
       <ul>
-        <li v-for="[key, value] in Object.entries(siteData.locales)" :key="key">
+        <li v-for="[key, value] in Object.entries($site.locales)" :key="key">
           <RouterLink :to="key">{{ value.lang }}</RouterLink>
         </li>
       </ul>

packages/client/src/app.ts

@@ -1,6 +1,6 @@
 import { clientConfigs } from '@internal/clientConfigs'
 import { createApp, createSSRApp, h } from 'vue'
-import { usePageLayout } from './composables/index.js'
+import { useData } from './composables/index.js'
 import { siteData } from './internal/siteData.js'
 import { createVueRouter } from './router/createVueRouter.js'
 import { setupGlobalComponents } from './setupGlobalComponents.js'
@@ -35,7 +35,7 @@ export const createVueApp: CreateVueAppFunction = async () => {
       )
 
       // get page layout
-      const pageLayout = usePageLayout()
+      const { pageLayout } = useData()
 
       // render layout and root components
       return () => [h(pageLayout.value), clientRootComponents]

packages/client/src/components/AutoLink.ts

@@ -2,7 +2,7 @@ import { isLinkWithProtocol } from '@vuepress/shared'
 import type { PropType, SlotsType, VNode } from 'vue'
 import { computed, defineComponent, h, toRef } from 'vue'
 import { useRoute } from 'vue-router'
-import { useSiteData } from '../composables/index.js'
+import { useSite } from '../composables/index.js'
 import { RouteLink } from './RouteLink.js'
 
 export interface AutoLinkConfig {
@@ -67,7 +67,7 @@ export const AutoLink = defineComponent({
   setup(props, { slots }) {
     const config = toRef(props, 'config')
     const route = useRoute()
-    const siteData = useSiteData()
+    const site = useSite()
 
     // If the link has non-http protocol
     const withProtocol = computed(() => isLinkWithProtocol(config.value.link))
@@ -102,7 +102,7 @@ export const AutoLink = defineComponent({
       // Should not be active in `exact` mode
       if (config.value.exact) return false
 
-      const localePaths = Object.keys(siteData.value.locales)
+      const localePaths = Object.keys(site.value.locales)
 
       return localePaths.length
         ? // Check all the locales

packages/client/src/components/Content.ts

@@ -1,5 +1,5 @@
 import { computed, defineAsyncComponent, defineComponent, h, watch } from 'vue'
-import { usePageComponent, usePageFrontmatter } from '../composables/index.js'
+import { useData } from '../composables/index.js'
 import { contentUpdatedCallbacks } from '../internal/contentUpdatedCallbacks'
 import { resolveRoute } from '../router/index.js'
 import type { ContentUpdatedReason } from '../types/index.js'
@@ -28,7 +28,7 @@ export const Content = defineComponent({
   },
 
   setup(props) {
-    const pageComponent = usePageComponent()
+    const { frontmatter, pageComponent } = useData()
     const ContentComponent = computed(() => {
       if (!props.path) return pageComponent.value
       const route = resolveRoute(props.path)
@@ -37,7 +37,6 @@ export const Content = defineComponent({
       )
     })
 
-    const frontmatter = usePageFrontmatter()
     watch(
       frontmatter,
       () => {

packages/client/src/composables/clientData.ts

@@ -0,0 +1,29 @@
+import type { InjectionKey } from 'vue'
+import { inject } from 'vue'
+import type { Data } from '../types/index.js'
+
+/**
+ * Injection key for vuepress data
+ */
+export const dataSymbol: InjectionKey<Data> = Symbol(
+  __VUEPRESS_DEV__ ? 'data' : '',
+)
+
+/**
+ * Returns VuePress data
+ */
+export const useData = <
+  Frontmatter extends Record<string, unknown> = Record<string, unknown>,
+  Page extends Record<string, unknown> = Record<string, unknown>,
+>(): Data<Frontmatter, Page> => {
+  const data = inject<Data<Frontmatter, Page>>(dataSymbol)
+  if (!data) {
+    throw new Error('useData() is called without provider.')
+  }
+  return data
+}
+
+// FIXME: remove this in stable
+
+/** @deprecated using `useData` instead */
+export const useClientData = useData

packages/client/src/composables/clientDataUtils.ts

@@ -0,0 +1,100 @@
+import type {
+  LayoutsRef,
+  PageComponentRef,
+  PageDataRef,
+  PageFrontmatterRef,
+  PageHeadRef,
+  PageLangRef,
+  PageLayoutRef,
+  RedirectsRef,
+  RouteLocaleRef,
+  RoutePathRef,
+  RoutesRef,
+  SiteDataRef,
+  SiteLocaleDataRef,
+} from '../types/index.js'
+import { useData } from './data.js'
+
+// page related
+
+/**
+ * Get page data
+ */
+export const usePage = <
+  T extends Record<string, unknown> = Record<string, unknown>,
+>(): PageDataRef<T> => useData<Record<string, unknown>, T>().page
+/**
+ * Get page frontmatter
+ */
+export const useFrontmatter = <
+  T extends Record<string, unknown> = Record<string, unknown>,
+>(): PageFrontmatterRef<T> => useData<T>().frontmatter
+/**
+ * Get page head
+ */
+export const useHead = (): PageHeadRef => useData().head
+/**
+ * Get page lang
+ */
+export const useLang = (): PageLangRef => useData().lang
+
+// route related
+
+/**
+ * Get routes map
+ */
+export const useRoutes = (): RoutesRef => useData().routes
+/**
+ * Get redirect records
+ */
+export const useRedirects = (): RedirectsRef => useData().redirects
+
+/**
+ * Get route locale
+ */
+export const useRouteLocale = (): RouteLocaleRef => useData().routeLocale
+/**
+ * Get route path
+ */
+export const useRoutePath = (): RoutePathRef => useData().routePath
+
+// site related
+/**
+ * Get site data
+ */
+export const useSite = (): SiteDataRef => useData().site
+/**
+ * Get site locale data
+ */
+export const useSiteLocale = (): SiteLocaleDataRef => useData().siteLocale
+
+// internal composables before `useData` was introduced, which are never expected to be called outside of vuePress/client
+// these are marked deprecated and kept for backward compatibility for now
+// FIXME: remove these in stable
+
+/** @deprecated use useData().pageComponent instead */
+export const usePageComponent = (): PageComponentRef => useData().pageComponent
+/** @deprecated use useData().pageLayout instead */
+export const usePageLayout = (): PageLayoutRef => useData().pageLayout
+/** @deprecated use useData().layouts instead */
+export const useLayouts = (): LayoutsRef => useData().layouts
+
+// original long composable names
+// these are kept for backward compatibility, and might not need to implicitly marked as deprecated
+
+/** Note: suggest using `usePage` instead */
+export const usePageData = <
+  T extends Record<string, unknown> = Record<string, unknown>,
+>(): PageDataRef<T> => useData<Record<string, unknown>, T>().page
+/** Note: suggest using `useFrontmatter` instead */
+export const usePageFrontmatter = <
+  T extends Record<string, unknown> = Record<string, unknown>,
+>(): PageFrontmatterRef<T> => useData<T>().frontmatter
+/** Note: suggest using `useHead` instead */
+export const usePageHead = (): PageHeadRef => useData().head
+/** Note: suggest using `useLang` instead */
+export const usePageLang = (): PageLangRef => useData().lang
+/** Note: suggest using `useSite` instead */
+export const useSiteData = (): SiteDataRef => useData().site
+/** Note: suggest using `useSiteLocale` instead */
+export const useSiteLocaleData = (): SiteLocaleDataRef => useData().siteLocale

packages/client/src/composables/data.ts

@@ -1,4 +1,4 @@
-export * from './clientData.js'
-export * from './clientDataUtils.js'
+export * from './data.js'
+export * from './dataUtils.js'
 export * from './onContentUpdated.js'
 export * from './updateHead.js'

packages/client/src/composables/dataUtils.ts

@@ -17,7 +17,7 @@ const INSPECTOR_NODE_INTERNAL = {
 const INSPECTOR_NODE_SITE = {
   id: 'SITE',
   label: 'Site',
-  keys: ['siteData', 'siteLocaleData'],
+  keys: ['site', 'siteLocale'],
 } as const satisfies InspectorNodeConfig
 
 const INSPECTOR_NODE_ROUTE = {
@@ -30,11 +30,11 @@ const INSPECTOR_NODE_PAGE = {
   id: 'PAGE',
   label: 'Page',
   keys: [
-    'pageData',
-    'pageFrontmatter',
-    'pageLang',
-    'pageHead',
-    'pageHeadTitle',
+    'page',
+    'frontmatter',
+    'lang',
+    'head',
+    'headTitle',
     'pageLayout',
     'pageComponent',
   ],

packages/client/src/composables/index.ts

@@ -1,15 +1,11 @@
 import { setupDevtoolsPlugin } from '@vue/devtools-api'
 import type { App } from 'vue'
 import { watch } from 'vue'
-import type { ClientData } from '../types/index.js'
+import type { Data } from '../types/index.js'
 import * as DEVTOOLS from './constants.js'
-import type {
-  ClientDataKey,
-  ClientDataValue,
-  InspectorNodeConfig,
-} from './types.js'
+import type { DataKey, DataValue, InspectorNodeConfig } from './types.js'
 
-export const setupDevtools = (app: App, clientData: ClientData): void => {
+export const setupDevtools = (app: App, clientData: Data): void => {
   setupDevtoolsPlugin(
     {
       // fix recursive reference
@@ -23,11 +19,11 @@ export const setupDevtools = (app: App, clientData: ClientData): void => {
     },
     (api) => {
       const clientDataEntries = Object.entries(clientData) as [
-        ClientDataKey,
-        ClientDataValue,
+        DataKey,
+        DataValue,
       ][]
-      const clientDataKeys = Object.keys(clientData) as ClientDataKey[]
-      const clientDataValues = Object.values(clientData) as ClientDataValue[]
+      const clientDataKeys = Object.keys(clientData) as DataKey[]
+      const clientDataValues = Object.values(clientData) as DataValue[]
 
       // setup component state
       api.on.inspectComponent((payload) => {
@@ -55,7 +51,7 @@ export const setupDevtools = (app: App, clientData: ClientData): void => {
           (node) => ({
             id: node.id,
             label: node.label,
-            children: node.keys.map((key: ClientDataKey) => ({
+            children: node.keys.map((key: DataKey) => ({
               id: key,
               label: key,
             })),
@@ -81,12 +77,12 @@ export const setupDevtools = (app: App, clientData: ClientData): void => {
         }
 
         // root nodes children state
-        if (clientDataKeys.includes(payload.nodeId as ClientDataKey)) {
+        if (clientDataKeys.includes(payload.nodeId as DataKey)) {
           payload.state = {
             [DEVTOOLS.INSPECTOR_STATE_SECTION_NAME]: [
               {
                 key: payload.nodeId,
-                value: clientData[payload.nodeId as ClientDataKey].value,
+                value: clientData[payload.nodeId as DataKey].value,
               },
             ],
           }

packages/client/src/devtools/constants.ts

@@ -1,10 +1,10 @@
 import type { CustomInspectorNode } from '@vue/devtools-kit'
-import type { ClientData } from '../types/index.js'
+import type { Data } from '../types/index.js'
 
-export type ClientDataKey = keyof ClientData
-export type ClientDataValue = ClientData[ClientDataKey]
+export type DataKey = keyof Data
+export type DataValue = Data[DataKey]
 
 export interface InspectorNodeConfig
   extends Pick<CustomInspectorNode, 'id' | 'label'> {
-  keys: ClientDataKey[]
+  keys: DataKey[]
 }