valaxy 0.28.0-beta.6 → 0.28.0

package/client/components/.exclude/ValaxyDebug.vue

@@ -0,0 +1,176 @@
+<script setup lang="ts">
+import { computed, ref } from 'vue'
+import { useRoute } from 'vue-router'
+import { useFrontmatter } from '../../composables/common'
+import { useScreenSize } from '../../composables/helper/useScreenSize'
+import { useLayout } from '../../composables/layout'
+import { useSiteConfig, useThemeConfig } from '../../config'
+import ValaxySvgLogo from '../ValaxySvgLogo.vue'
+
+const show = ref(true)
+const expanded = ref<Record<string, boolean>>({
+  breakpoints: true,
+  route: false,
+  frontmatter: false,
+  config: false,
+})
+
+function toggleSection(key: string) {
+  expanded.value[key] = !expanded.value[key]
+}
+
+// Breakpoints
+const screenSize = useScreenSize()
+const breakpoints = computed(() => [
+  { label: 'xs', value: screenSize.isXs.value },
+  { label: 'sm', value: screenSize.isSm.value },
+  { label: 'md', value: screenSize.isMd.value },
+  { label: 'lg', value: screenSize.isLg.value },
+  { label: 'xl', value: screenSize.isXl.value },
+  { label: '2xl', value: screenSize.is2xl.value },
+])
+
+// Route
+const route = useRoute()
+const routeInfo = computed(() => ({
+  path: route.path,
+  name: route.name as string,
+  layout: route.meta?.layout || 'default',
+  query: Object.keys(route.query).length ? route.query : undefined,
+  params: Object.keys(route.params).length ? route.params : undefined,
+}))
+
+// Frontmatter
+const frontmatter = useFrontmatter()
+const fmSummary = computed(() => {
+  const fm = frontmatter.value
+  if (!fm || !Object.keys(fm).length)
+    return null
+  return fm
+})
+
+// Config
+const siteConfig = useSiteConfig()
+const themeConfig = useThemeConfig()
+const layout = useLayout()
+
+const configSummary = computed(() => ({
+  theme: siteConfig.value.lang ? undefined : undefined,
+  lang: siteConfig.value.lang,
+  title: siteConfig.value.title,
+  url: siteConfig.value.url,
+  layout: layout.value,
+}))
+</script>
+
+<template>
+  <div
+    v-if="show"
+    class="valaxy-debug fixed bottom-4 left-2 z-9999 max-h-[80vh] w-72 overflow-y-auto rounded-lg bg-black/80 p-3 text-xs text-white shadow-lg backdrop-blur-sm"
+    @click.stop
+  >
+    <!-- Header -->
+    <div class="mb-2 flex items-center justify-between border-b border-white/20 pb-2">
+      <span class="flex items-center gap-1 font-bold text-cyan-400">
+        <ValaxySvgLogo class="size-4" />
+        Valaxy Debug
+      </span>
+      <button
+        class="rounded px-1 text-white/60 transition hover:bg-white/20 hover:text-white"
+        title="Close"
+        @click="show = false"
+      >
+        ✕
+      </button>
+    </div>
+
+    <!-- Breakpoints -->
+    <div class="mb-1">
+      <button
+        class="w-full rounded px-1 py-0.5 text-left font-bold text-emerald-400 transition hover:bg-white/10"
+        @click="toggleSection('breakpoints')"
+      >
+        {{ expanded.breakpoints ? '▾' : '▸' }} Breakpoints
+      </button>
+      <div v-if="expanded.breakpoints" class="mt-1 flex flex-wrap gap-1 pl-3">
+        <span
+          v-for="bp in breakpoints"
+          :key="bp.label"
+          class="rounded px-1.5 py-0.5"
+          :class="bp.value ? 'bg-emerald-500/30 text-emerald-300' : 'bg-white/5 text-white/40'"
+        >
+          {{ bp.label }}
+        </span>
+      </div>
+    </div>
+
+    <!-- Route -->
+    <div class="mb-1">
+      <button
+        class="w-full rounded px-1 py-0.5 text-left font-bold text-blue-400 transition hover:bg-white/10"
+        @click="toggleSection('route')"
+      >
+        {{ expanded.route ? '▾' : '▸' }} Route
+      </button>
+      <div v-if="expanded.route" class="mt-1 space-y-0.5 pl-3">
+        <div><span class="text-white/50">path:</span> {{ routeInfo.path }}</div>
+        <div><span class="text-white/50">name:</span> {{ routeInfo.name }}</div>
+        <div><span class="text-white/50">layout:</span> {{ routeInfo.layout }}</div>
+        <div v-if="routeInfo.query">
+          <span class="text-white/50">query:</span> {{ JSON.stringify(routeInfo.query) }}
+        </div>
+        <div v-if="routeInfo.params">
+          <span class="text-white/50">params:</span> {{ JSON.stringify(routeInfo.params) }}
+        </div>
+      </div>
+    </div>
+
+    <!-- Frontmatter -->
+    <div class="mb-1">
+      <button
+        class="w-full rounded px-1 py-0.5 text-left font-bold text-amber-400 transition hover:bg-white/10"
+        @click="toggleSection('frontmatter')"
+      >
+        {{ expanded.frontmatter ? '▾' : '▸' }} Frontmatter
+      </button>
+      <div v-if="expanded.frontmatter" class="mt-1 pl-3">
+        <pre v-if="fmSummary" class="max-h-48 overflow-auto whitespace-pre-wrap break-all rounded bg-white/5 p-1.5 text-white/80">{{ JSON.stringify(fmSummary, null, 2) }}</pre>
+        <span v-else class="text-white/40">No frontmatter</span>
+      </div>
+    </div>
+
+    <!-- Config -->
+    <div class="mb-1">
+      <button
+        class="w-full rounded px-1 py-0.5 text-left font-bold text-purple-400 transition hover:bg-white/10"
+        @click="toggleSection('config')"
+      >
+        {{ expanded.config ? '▾' : '▸' }} Config
+      </button>
+      <div v-if="expanded.config" class="mt-1 space-y-2 pl-3">
+        <div>
+          <div class="mb-0.5 text-white/50">
+            Site Config
+          </div>
+          <pre class="max-h-48 overflow-auto whitespace-pre-wrap break-all rounded bg-white/5 p-1.5 text-white/80">{{ JSON.stringify(configSummary, null, 2) }}</pre>
+        </div>
+        <div>
+          <div class="mb-0.5 text-white/50">
+            Theme Config
+          </div>
+          <pre class="max-h-48 overflow-auto whitespace-pre-wrap break-all rounded bg-white/5 p-1.5 text-white/80">{{ JSON.stringify(themeConfig, null, 2) }}</pre>
+        </div>
+      </div>
+    </div>
+  </div>
+
+  <!-- Collapsed toggle button -->
+  <button
+    v-if="!show"
+    class="fixed bottom-4 left-2 z-9999 rounded-lg bg-black/60 px-2 py-1 text-xs text-white/60 shadow-lg backdrop-blur-sm transition hover:bg-black/80 hover:text-white"
+    title="Open Valaxy Debug"
+    @click="show = true"
+  >
+    <ValaxySvgLogo class="size-4" />
+  </button>
+</template>

package/client/components/ValaxyOpenInEditor.vue

@@ -0,0 +1,53 @@
+<script lang="ts" setup>
+import { useData } from '../composables'
+
+const { page } = useData()
+
+const isDev = import.meta.env.DEV
+
+/**
+ * Open the current page source file in editor (dev mode only)
+ * Uses Vite's built-in `/__open-in-editor` endpoint
+ */
+function openInEditor() {
+  const filePath = page.value?.filePath
+  if (filePath) {
+    fetch(`${window.location.origin}/__open-in-editor?file=${encodeURIComponent(filePath)}`)
+      .catch((err) => {
+        console.error('[valaxy] Failed to open in editor:', err)
+      })
+  }
+}
+</script>
+
+<template>
+  <button
+    v-if="isDev"
+    class="valaxy-open-in-editor"
+    title="Open in Editor"
+    @click="openInEditor"
+  >
+    <slot>
+      <div i-ri-code-s-slash-line />
+    </slot>
+  </button>
+</template>
+
+<style>
+.valaxy-open-in-editor {
+  display: inline-flex;
+  align-items: center;
+  cursor: pointer;
+  opacity: 0.4;
+  transition: opacity 0.2s;
+  background: none;
+  border: none;
+  padding: 0;
+  color: inherit;
+  font-size: inherit;
+}
+
+.valaxy-open-in-editor:hover {
+  opacity: 1;
+}
+</style>

package/client/composables/app/useValaxyApp.ts

@@ -1,12 +1,8 @@
 import { definePerson, defineWebPage, defineWebSite, useSchemaOrg } from '@unhead/schema-org/vue'
 import { useSeoMeta } from '@unhead/vue'
-
-// TODO: add docs to override ValaxyApp
 import { computed } from 'vue'
 import { useI18n } from 'vue-i18n'
-
 import { useRoute } from 'vue-router'
-
 import { useFrontmatter, useLocale, useValaxyHead, useValaxyI18n } from '../../composables'
 import { useTimezone } from '../../composables/global'
 // https://github.com/vueuse/head
@@ -16,7 +12,6 @@ import { useSiteConfig } from '../../config'
 
 export function useValaxyApp() {
   const siteConfig = useSiteConfig()
-  // todo, allow user config
   const fm = useFrontmatter()
 
   const { locale } = useI18n()
@@ -32,7 +27,6 @@ export function useValaxyApp() {
   }
 
   // seo
-  // todo: get first image url from markdown
   const siteUrl = computed(() => fm.value.url || siteConfig.value.url)
   const description = computed(() => $tO(fm.value.excerpt) || $tO(fm.value.description) || $t(siteConfig.value.description))
 
@@ -43,7 +37,7 @@ export function useValaxyApp() {
     ogLocaleAlternate: computed(() => siteConfig.value.languages.filter(l => l !== locale.value)),
     ogSiteName: computed(() => $t(siteConfig.value.title)),
     ogTitle: computed(() => $tO(fm.value.title) || $t(siteConfig.value.title)),
-    ogImage: computed(() => fm.value.ogImage || fm.value.cover || siteConfig.value.favicon),
+    ogImage: computed(() => fm.value.ogImage || fm.value.cover || fm.value.firstImage || siteConfig.value.favicon),
     ogType: 'website',
     ogUrl: siteUrl,
   })

package/client/composables/categories.ts

@@ -1,47 +1,11 @@
 import type { MaybeRef } from 'vue'
 import type { Post } from '../../types'
+import type { CategoryList } from './category-utils'
 import { computed, unref } from 'vue'
 import { useSiteStore } from '../stores'
 
-/**
- * 基础分类
- */
-export interface BaseCategory {
-  /**
-   * 分类下的文章数量
-   */
-  total: number
-}
-
-/**
- * @en
- * Category list
- *
- * @zh
- * 分类列表
- */
-export interface CategoryList {
-  /**
-   * category name
-   */
-  name: string
-  /**
-   * total posts
-   */
-  total: number
-  children: Map<string, Post | CategoryList>
-}
-export type Category = CategoryList
-export type Categories = Map<string, Post | CategoryList>
-
-/**
- * For theme development, you can use this function to determine whether the category is a category list.
- * @todo write unit test
- * @param category
- */
-export function isCategoryList(category: any): category is CategoryList {
-  return category.children
-}
+export type { BaseCategory, Categories, Category, CategoryList } from './category-utils'
+export { isCategoryList, removeItemFromCategory } from './category-utils'
 
 /**
  * get categories from posts
@@ -158,20 +122,3 @@ export function useCategories(category?: MaybeRef<string>, posts: Post[] = []) {
     }
   })
 }
-
-/**
- * remove item from category
- * @param categoryList
- * @param categoryName
- */
-export function removeItemFromCategory(categoryList: CategoryList, categoryName: string) {
-  if (isCategoryList(categoryList)) {
-    const categoryArr = categoryName.split('/')
-    categoryList.children.delete(categoryArr[0])
-  }
-}
-
-/**
- * @deprecated use `useCategories` instead
- */
-export const useCategory = useCategories

package/client/composables/category-utils.ts

@@ -0,0 +1,50 @@
+import type { Post } from '../../types'
+
+/**
+ * 基础分类
+ */
+export interface BaseCategory {
+  /**
+   * 分类下的文章数量
+   */
+  total: number
+}
+
+/**
+ * @en
+ * Category list
+ *
+ * @zh
+ * 分类列表
+ */
+export interface CategoryList {
+  /**
+   * category name
+   */
+  name: string
+  /**
+   * total posts
+   */
+  total: number
+  children: Map<string, Post | CategoryList>
+}
+export type Category = CategoryList
+export type Categories = Map<string, Post | CategoryList>
+
+/**
+ * For theme development, you can use this function to determine whether the category is a category list.
+ * @param category
+ */
+export function isCategoryList(category: unknown): category is CategoryList {
+  return !!category && typeof category === 'object' && 'children' in category && category.children instanceof Map
+}
+
+/**
+ * remove item from category
+ * @param categoryList
+ * @param categoryName
+ */
+export function removeItemFromCategory(categoryList: CategoryList, categoryName: string) {
+  const categoryArr = categoryName.split('/')
+  categoryList.children.delete(categoryArr[0])
+}

package/client/composables/index.ts

@@ -4,6 +4,7 @@ export * from './app'
 export * from './back'
 // for classify
 export * from './categories'
+export * from './category-utils'
 export * from './collections'
 
 // common

package/client/composables/locale.ts

@@ -1,12 +1,12 @@
 import type { Ref } from 'vue'
+import type { TaxonomyNamespace } from '../../shared/utils/i18n'
 import { isClient, useStorage } from '@vueuse/core'
 import dayjs from 'dayjs'
-import { computed } from 'vue'
 
+import { computed, watch } from 'vue'
 // not optimize deps all locales
 import { useI18n } from 'vue-i18n'
-import { tObject } from '../../shared/utils/i18n'
-import { LOCALE_PREFIX } from '../utils'
+import { isLocaleKey, resolveTaxonomyLocaleKey, stripLocalePrefix, tObject } from '../../shared/utils/i18n'
 import 'dayjs/locale/en'
 import 'dayjs/locale/zh-cn'
 
@@ -63,13 +63,16 @@ export function useLocale() {
 export function useLocaleTitle(fm: Ref<{
   title?: string | Record<string, string>
 } | null>) {
-  const { locale } = useI18n()
+  const { t, locale } = useI18n()
   return computed(() => {
     if (!fm.value)
       return ''
 
     const lang = locale.value
-    return tObject(fm.value.title || '', lang) || ''
+    const title = tObject(fm.value.title || '', lang) || ''
+    if (typeof title === 'string' && isLocaleKey(title))
+      return t(stripLocalePrefix(title))
+    return title
   })
 }
 
@@ -79,16 +82,19 @@ export function useLocaleTitle(fm: Ref<{
  * 会从 locales/ 目录中获取对应的翻译
  */
 export function useValaxyI18n() {
-  const { t, locale } = useI18n()
+  const { t, te, locale } = useI18n()
+  const termCache = new Map<string, string>()
+
+  // Clear cache on locale switches so each composable instance stays bounded.
+  watch(locale, () => termCache.clear())
 
   /**
    * translate `$locale:key`
    * @param key
    */
   const $t = (key: string) => {
-    if (key.startsWith(LOCALE_PREFIX)) {
-      return t(key.slice(LOCALE_PREFIX.length))
-    }
+    if (isLocaleKey(key))
+      return t(stripLocalePrefix(key))
     return key
   }
 
@@ -104,6 +110,47 @@ export function useValaxyI18n() {
     return tObject(data || '', locale.value)
   }
 
+  /**
+   * @en
+   * Translate a taxonomy term.
+   *
+   * Resolution order:
+   * 1. `$locale:` prefix → strip and translate via `t()`
+   * 2. Locale key `{namespace}.{key}` exists → translate via `t()`
+   * 3. Fallback → return the original key as-is
+   *
+   * The result is cached by `locale + namespace + key` to avoid repeated
+   * `te()` / `t()` lookups in tag clouds and category trees.
+   *
+   * @zh
+   * 翻译 taxonomy 术语。
+   *
+   * 解析顺序：
+   * 1. `$locale:` 前缀 → 去掉前缀后通过 `t()` 翻译
+   * 2. locale 中存在 `{namespace}.{key}` → 通过 `t()` 翻译
+   * 3. 兜底 → 原样返回
+   *
+   * 结果会按 `locale + namespace + key` 做轻量缓存，
+   * 避免标签云和分类树中重复执行 `te()` / `t()`。
+   */
+  const $tTerm = (namespace: TaxonomyNamespace, key: string) => {
+    const cacheKey = `${locale.value}:${namespace}:${key}`
+    const cached = termCache.get(cacheKey)
+    if (cached !== undefined)
+      return cached
+
+    const { localeKey, isExplicitLocaleKey } = resolveTaxonomyLocaleKey(namespace, key)
+    const result = isExplicitLocaleKey || te(localeKey)
+      ? `${t(localeKey)}`
+      : key
+
+    termCache.set(cacheKey, result)
+    return result
+  }
+
+  const $tTag = (key: string) => $tTerm('tag', key)
+  const $tCategory = (key: string) => $tTerm('category', key)
+
   return {
     locale,
     /**
@@ -111,5 +158,17 @@ export function useValaxyI18n() {
      */
     $t,
     $tO,
+    /**
+     * translate taxonomy term (auto-lookup `{namespace}.{key}` in locale files)
+     */
+    $tTerm,
+    /**
+     * translate tag name (auto-lookup `tag.{key}` in locale files)
+     */
+    $tTag,
+    /**
+     * translate category name (auto-lookup `category.{key}` in locale files)
+     */
+    $tCategory,
   }
 }

package/client/composables/outline/anchor.ts

@@ -49,7 +49,7 @@ export function useActiveAnchor(
 
   /**
    * 长目录自动滚动
-   * @TODO add e2e test
+   * @see e2e/theme-yun/outline.spec.ts
    */
   const checkActiveLinkInViewport = () => {
     const activeLink = prevActiveLink

package/client/composables/post/index.ts

@@ -6,15 +6,18 @@ import { orderByMeta, useSiteConfig } from 'valaxy'
 import { computed } from 'vue'
 import { useI18n } from 'vue-i18n'
 import { useRouterStore } from '../../stores'
-import { tObject } from '../../utils'
+import { isLocaleKey, stripLocalePrefix, tObject } from '../../utils'
 
 export * from './usePagination'
 export * from './usePrevNext'
 
 export function usePostTitle(post: ComputedRef<Post>) {
-  const { locale } = useI18n()
+  const { t, locale } = useI18n()
   return computed(() => {
-    return tObject(post.value.title || '', locale.value)
+    const title = tObject(post.value.title || '', locale.value)
+    if (typeof title === 'string' && isLocaleKey(title))
+      return t(stripLocalePrefix(title))
+    return title
   })
 }
 

package/client/composables/tags.ts

@@ -51,8 +51,3 @@ export function useTags() {
     return tagMap
   })
 }
-
-/**
- * @deprecated use `useTags` instead
- */
-export const useTag = useTags

package/client/modules/components.ts

@@ -1,5 +1,6 @@
 import type { ValaxySSGContext } from '../setups'
 
+import { defineAsyncComponent } from 'vue'
 import AppLink from '../components/AppLink.vue'
 import ValaxyTranslate from '../components/builtin/ValaxyTranslate.vue'
 
@@ -10,4 +11,10 @@ import ValaxyTranslate from '../components/builtin/ValaxyTranslate.vue'
 export function registerGlobalComponents(ctx: ValaxySSGContext) {
   ctx.app.component('AppLink', AppLink)
   ctx.app.component('VT', ValaxyTranslate)
+
+  // DEV-only: register ValaxyDebug component (tree-shaken in production)
+  if (import.meta.env.DEV) {
+    const ValaxyDebug = defineAsyncComponent(() => import('../components/.exclude/ValaxyDebug.vue'))
+    ctx.app.component('ValaxyDebug', ValaxyDebug)
+  }
 }

package/client/modules/valaxy.ts

@@ -14,6 +14,7 @@ import type { PageDataPayload } from '../../types'
 import type { ValaxySSGContext } from '../setups'
 import { ensureSuffix } from '@antfu/utils'
 import { useStorage } from '@vueuse/core'
+import { nextTick, watch } from 'vue'
 import { createI18n } from 'vue-i18n'
 
 // @ts-expect-error virtual
@@ -52,11 +53,35 @@ export const i18n = createI18n({
 })
 
 export async function install({ app, router }: ValaxySSGContext, config: ComputedRef<ValaxyConfig<DefaultTheme.Config>>) {
-  const locale = useStorage('valaxy-locale', config?.value.siteConfig.lang || 'en')
-  i18n.global.locale.value = locale.value
+  const defaultLang = config?.value.siteConfig.lang || 'en'
+
+  // During SSR/SSG build **and** the initial client hydration pass we must
+  // keep the locale at `defaultLang` so that the rendered HTML matches on
+  // both sides — no hydration mismatch for any i18n-dependent attribute
+  // (title, class, text content, etc.).
+  //
+  // The stored user preference is restored **after** hydration is complete
+  // (router.isReady + nextTick) so Vue can patch the DOM normally.
+  i18n.global.locale.value = defaultLang
 
   app.use(i18n)
-  router.isReady().then(() => {
+
+  router.isReady().then(async () => {
+    // Wait for the hydration to finish before restoring the stored locale.
+    await nextTick()
+
+    const storedLocale = useStorage('valaxy-locale', defaultLang)
+
+    // Apply the stored locale (if different from default)
+    if (storedLocale.value && storedLocale.value !== i18n.global.locale.value)
+      i18n.global.locale.value = storedLocale.value
+
+    // Keep i18n locale in sync when the stored value changes later
+    watch(storedLocale, (val) => {
+      if (val)
+        i18n.global.locale.value = val
+    })
+
     handleHMR(router)
   })
 }

package/dist/node/cli/index.mjs

@@ -1,7 +1,7 @@
 import 'node:process';
 import 'yargs';
 import 'yargs/helpers';
-export { c as cli, I as registerDevCommand, W as run, Z as startValaxyDev } from '../../shared/valaxy.BVsZMcdc.mjs';
+export { c as cli, I as registerDevCommand, W as run, Z as startValaxyDev } from '../../shared/valaxy.DQ6HsU2J.mjs';
 import 'node:os';
 import 'node:path';
 import 'consola';