valaxy 0.18.10 → 0.19.2

package/client/App.vue

@@ -16,14 +16,13 @@ import { definePerson, defineWebPage, defineWebSite, useSchemaOrg } from '@unhea
 // they will be rendered correctly in the html results with vite-ssg
 import { useSiteConfig } from './config'
 import ValaxyAddons from './components/ValaxyAddons.vue'
-import { isDark, useFrontmatter } from './composables'
+import { useFrontmatter } from './composables'
 
 // <link rel="apple-touch-icon" href="/pwa-192x192.png">
 // <link rel="mask-icon" href="/safari-pinned-tab.svg" color="#00aba9">
 
 const siteConfig = useSiteConfig()
 // todo, allow user config
-const themeColor = computed(() => isDark.value ? '#000' : '#ffffff')
 const fm = useFrontmatter()
 
 const { locale } = useI18n()
@@ -41,14 +40,6 @@ useHead({
   ],
   meta: [
     { name: 'description', content: computed(() => siteConfig.value.description) },
-    {
-      name: 'theme-color',
-      content: themeColor,
-    },
-    {
-      name: 'msapplication-TileColor',
-      content: themeColor,
-    },
     {
       name: 'generator',
       content: `Valaxy ${pkg.version}`,
@@ -102,5 +93,9 @@ useSchemaOrg([
   <ValaxyThemeApp />
   <ValaxyAddons />
   <ValaxyUserApp />
-  <RouterView />
+  <router-view v-slot="{ Component, route }">
+    <transition name="app-transition">
+      <component :is="Component" :key="route" />
+    </transition>
+  </router-view>
 </template>

package/client/components/builtin/ValaxyMermaid.vue

@@ -16,11 +16,10 @@ pie
 import { getCurrentInstance, ref, watch, watchEffect } from 'vue'
 
 import { isClient } from '@vueuse/core'
+import { useAppStore } from 'valaxy'
 import { renderMermaid } from '../../modules/mermaid'
 import ShadowRoot from '../internals/ShadowRoot.vue'
 
-import { isDark } from '../../composables'
-
 const props = defineProps<{
   code: string
   scale?: number
@@ -31,6 +30,8 @@ const vm = getCurrentInstance()
 const el = ref<ShadowRoot>()
 const html = ref('')
 
+const appStore = useAppStore()
+
 if (isClient) {
   // dynamic import to reduce initial bundle size
   import('mermaid').then(m => m.default)
@@ -47,7 +48,7 @@ if (isClient) {
           mermaid,
           props.code || '',
           {
-            theme: props.theme || (isDark.value ? 'dark' : undefined),
+            theme: props.theme || (appStore.isDark ? 'dark' : undefined),
             ...vm!.attrs,
           },
         )

package/client/composables/aside.ts

@@ -1,11 +1,18 @@
-import { ref } from 'vue'
+import { useMediaQuery } from '@vueuse/core'
+import { useSidebar } from 'valaxy'
+import { computed } from 'vue'
 
 export function useAside() {
-  // const { hasSidebar } = useSidebar()
-  // const is960 = useMediaQuery('(min-width: 960px)')
-  // const is1280 = useMediaQuery('(min-width: 1280px)')
+  const { hasSidebar } = useSidebar()
+  const is960 = useMediaQuery('(min-width: 960px)')
+  const is1280 = useMediaQuery('(min-width: 1280px)')
 
-  const isAsideEnabled = ref(true)
+  const isAsideEnabled = computed(() => {
+    if (!is1280.value && !is960.value)
+      return false
+
+    return hasSidebar.value ? is1280.value : is960.value
+  })
 
   return {
     isAsideEnabled,

package/client/composables/categories.ts

@@ -13,6 +13,13 @@ export interface BaseCategory {
   total: number
 }
 
+/**
+ * @en
+ * Category list
+ *
+ * @zh
+ * 分类列表
+ */
 export interface CategoryList {
   /**
    * category name
@@ -27,7 +34,11 @@ export interface CategoryList {
 export type Category = CategoryList
 export type Categories = Map<string, Post | CategoryList>
 
-// todo write unit test
+/**
+ * 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
 }

package/client/composables/dark.ts

@@ -1,44 +1,83 @@
-import { isClient, useDark, useToggle } from '@vueuse/core'
+import type { UseDarkOptions } from '@vueuse/core'
+import { useDark, useToggle } from '@vueuse/core'
+import { computed } from 'vue'
 
-if (isClient)
-  import('valaxy/client/styles/common/view-transition.css')
+export function useValaxyDark(options: {
+  /**
+   * Options for `useDark`
+   * disableTransition default is `true`
+   * @see https://vueuse.org/core/useDark
+   * @url https://paco.me/writing/disable-theme-transitions
+   */
+  useDarkOptions?: UseDarkOptions
+  /**
+   * Enable circle transition when toggling dark mode
+   * Then use `toggleDarkWithTransition` instead of `toggleDark`
+   */
+  circleTransition?: boolean
 
-export const isDark = useDark()
-export const toggleDark = useToggle(isDark)
-
-export function toggleDarkWithTransition(event: MouseEvent, options: { duration?: number, easing?: EffectTiming['easing'] } = {}) {
-  // @ts-expect-error startViewTransition is not defined
-  if (!document.startViewTransition) {
-    toggleDark()
-    return
+  themeColor?: {
+    light?: string
+    dark?: string
   }
+} = {}) {
+  const isDark = useDark(options.useDarkOptions)
+  const toggleDark = useToggle(isDark)
+
+  const themeColor = computed(() => isDark.value
+    ? (options.themeColor?.dark || '#000')
+    : (options.themeColor?.light || '#fff'))
+
+  if (options.circleTransition)
+    import('valaxy/client/styles/common/view-transition.css')
 
-  const x = event.clientX
-  const y = event.clientY
-  const endRadius = Math.hypot(
-    Math.max(x, innerWidth - x),
-    Math.max(y, innerHeight - y),
-  )
-
-  // @ts-expect-error startViewTransition is not defined
-  const transition = document.startViewTransition(() => {
-    toggleDark()
-  })
-
-  transition.ready.then(() => {
-    const clipPath = [
-      `circle(0px at ${x}px ${y}px)`,
-      `circle(${endRadius}px at ${x}px ${y}px)`,
-    ]
-    document.documentElement.animate(
-      {
-        clipPath: isDark.value ? clipPath.reverse() : clipPath,
-      },
-      {
-        duration: options.duration || 300,
-        easing: options.easing || 'ease-in',
-        pseudoElement: isDark.value ? '::view-transition-old(root)' : '::view-transition-new(root)',
-      },
+  function toggleDarkWithTransition(event: MouseEvent, options: { duration?: number, easing?: EffectTiming['easing'] } = {}) {
+    // @ts-expect-error startViewTransition is not defined
+    if (!document.startViewTransition) {
+      toggleDark()
+      return
+    }
+
+    const x = event.clientX
+    const y = event.clientY
+    const endRadius = Math.hypot(
+      Math.max(x, innerWidth - x),
+      Math.max(y, innerHeight - y),
     )
-  })
+
+    // @ts-expect-error startViewTransition is not defined
+    const transition = document.startViewTransition(() => {
+      toggleDark()
+    })
+
+    transition.ready.then(() => {
+      const clipPath = [
+        `circle(0px at ${x}px ${y}px)`,
+        `circle(${endRadius}px at ${x}px ${y}px)`,
+      ]
+      document.documentElement.animate(
+        {
+          clipPath: isDark.value ? clipPath.reverse() : clipPath,
+        },
+        {
+          duration: options.duration || 300,
+          easing: options.easing || 'ease-in',
+          pseudoElement: isDark.value ? '::view-transition-old(root)' : '::view-transition-new(root)',
+        },
+      )
+    })
+  }
+
+  return {
+    /**
+     * Dark mode state, sync with app store
+     *
+     * You can also use `const appStore = useAppStore(); appStore.isDark` to get the value
+     */
+    isDark,
+    themeColor,
+
+    toggleDark,
+    toggleDarkWithTransition,
+  }
 }

package/client/composables/layout.ts

@@ -1,10 +1,18 @@
+import { useMediaQuery } from '@vueuse/core'
 import { computed } from 'vue'
 import { useRoute } from 'vue-router'
 
 export function useLayout(layout?: string) {
   const route = useRoute()
   if (layout)
-    return computed(() => route.meta.layout === layout)
+    return computed(() => route.meta?.layout === layout)
   else
-    return computed(() => route.meta.layout)
+    return computed(() => route.meta?.layout)
+}
+
+/**
+ * is mobile media query
+ */
+export function useMobile() {
+  return useMediaQuery('(max-width: 768px)')
 }

package/client/composables/outline/headers.ts

@@ -3,6 +3,13 @@ import type { DefaultTheme, Header } from 'valaxy/types'
 import { onContentUpdated } from '../../utils'
 import { useFrontmatter, useThemeConfig } from '../..'
 
+/**
+ * @en
+ * Menu item, the title menu parsed from the article.
+ *
+ * @zh
+ * 菜单项，从文章中解析出的标题菜单。
+ */
 export type MenuItem = Omit<Header, 'slug' | 'children'> & {
   children?: MenuItem[]
 }
@@ -105,7 +112,11 @@ export function useOutline() {
  * get headers from document directly
  */
 export function getHeaders(range: Exclude<DefaultTheme.Config['outline'], false>) {
-  const headers = Array.from(document.querySelectorAll('.markdown-body :where(h1,h2,h3,h4,h5,h6)'))
+  // when transition, the markdown-body will be two
+  // the first is the old one, the last is the new one
+  const markdownBodyElements = document.querySelectorAll('.markdown-body') as NodeListOf<HTMLElement>
+  const markdownBody = markdownBodyElements[markdownBodyElements.length - 1]
+  const headers = Array.from(markdownBody.querySelectorAll('.markdown-body :where(h1,h2,h3,h4,h5,h6)'))
     .filter(el => el.id && el.hasChildNodes())
     .map((el) => {
       const level = Number(el.tagName[1])

package/client/composables/sidebar.ts

@@ -1,6 +1,6 @@
-import { computed, ref } from 'vue'
+import { computed, ref, watchEffect } from 'vue'
 import { useFrontmatter } from './common'
-import { useLayout } from './layout'
+import { useLayout, useMobile } from './layout'
 
 /**
  * helper for sidebar
@@ -9,6 +9,7 @@ export function useSidebar() {
   const isOpen = ref(false)
   const fm = useFrontmatter()
   const layout = useLayout()
+
   const hasSidebar = computed(() => {
     return (
       fm.value.sidebar !== false
@@ -36,3 +37,41 @@ export function useSidebar() {
     toggle,
   }
 }
+
+/**
+ * dynamic left sidebar logic
+ * - sidebar is hidden by default when home or mobile
+ * - sidebar is shown by default when not home and not mobile
+ * - sidebar can be toggled by user
+ */
+export function useDynamicLeftSidebar() {
+  const layout = useLayout()
+  const isMobile = useMobile()
+  const isOpen = ref(isMobile.value ? false : layout.value !== 'home')
+
+  watchEffect(() => {
+    if (isMobile.value)
+      close()
+    else if (layout.value !== 'home')
+      open()
+  })
+
+  function open() {
+    isOpen.value = true
+  }
+
+  function close() {
+    isOpen.value = false
+  }
+
+  function toggle() {
+    isOpen.value ? close() : open()
+  }
+
+  return {
+    isOpen,
+    open,
+    close,
+    toggle,
+  }
+}

package/client/composables/tags.ts

@@ -2,6 +2,15 @@ import { computed } from 'vue'
 import type { Post } from '../../types'
 import { useSiteStore } from '../stores'
 
+/**
+ * @en
+ * Tag list, key is tag name, value is the object of tag.
+ * - count: the number of posts with this tag.
+ *
+ * @zh
+ * 标签列表，键是标签名，值是标签对象。
+ * - count: 使用该标签的文章数量。
+ */
 export type Tags = Map<string, {
   count: number
 }>

package/client/locales/en.yml

@@ -35,8 +35,8 @@ sidebar:
 
 post:
   decrypt: DECRYPT
-  posted: Posted on
-  edited: Edited on
+  posted: 'Posted on '
+  edited: 'Edited on '
   created: Created
   modified: Modified
   edit: Edit this post

package/client/locales/zh-CN.yml

@@ -49,7 +49,7 @@ post:
   view_link: 查看链接
   read_more: 阅读更多
   cover: 封面
-  time_warning: '本文最后更新于{ago}，文中所描述的信息可能已发生改变。'
+  time_warning: '本文最后更新于 {ago}，文中所描述的信息可能已发生改变。'
   copyright:
     author: 本文作者
     link: 本文链接

package/client/main.ts

@@ -1,3 +1,15 @@
+// reset styles, load css before app
+// import '@unocss/reset/tailwind.css'
+// https://unocss.dev/guide/style-reset#tailwind-compat
+// minus the background color override for buttons to avoid conflicts with UI frameworks
+import '@unocss/reset/tailwind-compat.css'
+// css
+import './styles/css/css-vars.css'
+import './styles/css/main.css'
+// generate user styles
+import '/@valaxyjs/styles'
+import 'uno.css'
+
 import type { ViteSSGContext } from 'vite-ssg'
 import { ViteSSG } from 'vite-ssg'
 
@@ -9,16 +21,6 @@ import AppLink from './components/AppLink.vue'
 
 import App from './App.vue'
 
-// reset styles
-// import '@unocss/reset/tailwind.css'
-// https://unocss.dev/guide/style-reset#tailwind-compat
-// minus the background color override for buttons to avoid conflicts with UI frameworks
-import '@unocss/reset/tailwind-compat.css'
-
-// generate user styles
-import '/@valaxyjs/styles'
-import 'uno.css'
-
 import setupMain from './setup/main'
 import { setupValaxyDevTools } from './utils/dev'
 

package/client/setup/main.ts

@@ -20,9 +20,7 @@ export default function setupMain(ctx: ViteSSGContext, config: ComputedRef<Valax
   const injection_arg = ctx
 
   installValaxy(ctx, config)
-
   installSchema(ctx)
-
   installPinia(ctx)
   installNprogress(ctx)
 

package/client/setup/mermaid.ts

@@ -3,6 +3,13 @@
 import { defineMermaidSetup } from 'valaxy'
 import type { MermaidOptions } from '../types'
 
+/**
+ * @en
+ * Extend the Mermaid configuration.
+ *
+ * @zh
+ * 扩展 Mermaid 配置。
+ */
 export default defineMermaidSetup(() => {
   // eslint-disable-next-line prefer-const
   let injection_return: MermaidOptions = {

package/client/setups.ts

@@ -2,6 +2,14 @@ import type { ViteSSGContext } from 'vite-ssg'
 import type { Awaitable } from '@antfu/utils'
 import type { MermaidOptions } from './types'
 
+/**
+ * @see https://github.com/antfu-collective/vite-ssg
+ * @en
+ * The context object for the application setup function.
+ *
+ * @zh
+ * 应用 setup 函数的上下文对象。（包括了 ViteSSG context）
+ */
 export type AppContext = ViteSSGContext
 
 export type AppSetup = (ctx: AppContext) => Awaitable<void>
@@ -9,6 +17,13 @@ export type AppSetup = (ctx: AppContext) => Awaitable<void>
 // client
 export type MermaidSetup = () => Partial<MermaidOptions> | void
 
+/**
+ * @en
+ * Define the setup function for the client application.
+ *
+ * @zh
+ * 扩展客户端应用的 setup 函数。
+ */
 export function defineAppSetup(fn: AppSetup) {
   return fn
 }

package/client/shims.d.ts

@@ -0,0 +1,3 @@
+declare module 'virtual:valaxy-theme' {
+  export default any
+}

package/client/stores/app.ts

@@ -1,19 +1,35 @@
 import { acceptHMRUpdate, defineStore } from 'pinia'
 import { useToggle } from '@vueuse/core'
 import { ref } from 'vue'
+import { useMobile, useThemeConfig, useValaxyDark } from 'valaxy'
 
+/**
+ * Global store for users
+ * @example
+ * ```ts
+ * import { useAppStore } from 'valaxy'
+ * const appStore = useAppStore()
+ * ```
+ */
 export const useAppStore = defineStore('app', () => {
+  const themeConfig = useThemeConfig()
+  const { isDark, toggleDark, toggleDarkWithTransition, themeColor } = useValaxyDark(themeConfig.value.valaxyDarkOptions)
+
+  const isMobile = useMobile()
   const showLoading = ref(true)
 
-  const [isSidebarOpen, toggleSidebar] = useToggle(false)
   // right sidebar with toc
   const [isRightSidebarOpen, toggleRightSidebar] = useToggle(false)
 
   return {
-    showLoading,
+    isMobile,
+    // for dark
+    isDark,
+    themeColor,
+    toggleDark,
+    toggleDarkWithTransition,
 
-    isSidebarOpen,
-    toggleSidebar,
+    showLoading,
 
     isRightSidebarOpen,
     toggleRightSidebar,

package/client/styles/css/css-vars.css

@@ -0,0 +1,19 @@
+:root {
+  --va-c-bg: #ffffff;
+  --va-c-bg-light: #ffffff;
+  --va-c-bg-dark: #fafafa;
+  --va-c-bg-opacity: rgba(255, 255, 255, 0.8);
+  --va-c-bg-soft: #f9f9f9;
+  --va-c-bg-alt: #f9f9f9;
+  --va-c-bg-mute: #f1f1f1;
+}
+
+html.dark {
+  --va-c-bg: #1b1b1f;
+  --va-c-bg-light: #202127;
+  --va-c-bg-dark: #1a1a1a;
+  --va-c-bg-opacity: rgba(0, 0, 0, 0.8);
+  --va-c-bg-alt: #161618;
+  --va-c-bg-soft: #202127;
+  --va-c-bg-mute: #2f2f2f;
+}

package/client/styles/{global/index.scss → css/main.css}

@@ -6,7 +6,7 @@ body,
   line-height: 2;
 }
 
-body {
+html {
   background-color: var(--va-c-bg);
 }
 

package/client/styles/css-vars.scss

@@ -39,7 +39,7 @@ $c-primary: #0078e7 !default;
 }
 
 // dark
-.dark {
+html.dark {
   color-scheme: dark;
 
   @include set-css-var-from-map(palette.$dark);

package/client/styles/index.scss

@@ -4,7 +4,6 @@ $c-primary: #0078e7 !default;
 
 // global css
 @use "./global/reset.scss" as *;
-@use "./global/index.scss" as *;
 @use "./global/nprogress.scss" as *;
 
 // https://github.com/valaxyjs/css-i18n

package/client/styles/palette.scss

@@ -46,15 +46,6 @@ $light: map.merge(
 
     "border-color": #222,
 
-    "c-bg": white,
-    "c-bg-light": white,
-    "c-bg-dark": #fafafa,
-    "c-bg-opacity": rgba(255, 255, 255 , 0.8),
-
-    "c-bg-soft": #f9f9f9,
-    "c-bg-alt": #f9f9f9,
-    "c-bg-mute": #f1f1f1,
-
     "c-text": #333,
     "c-text-light": #555,
     "c-text-lighter": #666,
@@ -71,15 +62,6 @@ $dark: map.merge(
   (
     "border-color": #e6e6e6,
 
-    "c-bg": #1b1b1f,
-    "c-bg-light": #202127,
-    "c-bg-dark": #1a1a1a,
-    "c-bg-opacity": rgba(0, 0, 0,  0.8),
-
-    "c-bg-alt": #161618,
-    "c-bg-soft": #202127,
-    "c-bg-mute": #2f2f2f,
-
     "c-text": #f2f2f2,
     "c-text-light": #ddd,
     "c-text-lighter": #eee,

package/client/types/index.ts

@@ -3,4 +3,7 @@ import type mermaid from 'mermaid'
 
 export type UserModule = (ctx: ViteSSGContext) => void
 
+/**
+ * @see https://mermaid.js.org/config/schema-docs/config.html#mermaid-config-schema
+ */
 export type MermaidOptions = (typeof mermaid.initialize) extends (a: infer A) => any ? A : never

package/client/utils/router.ts

@@ -1,7 +1,18 @@
 import type { Router } from 'vue-router'
 
+/**
+ * @en
+ * Options for scrolling to a target element.
+ *
+ * @zh
+ * 滚动到目标元素的选项。
+ */
 export interface ScrollToOptions {
   /**
+   * @en
+   * Whether to scroll smoothly.
+   *
+   * @zh
    * 平滑滚动
    */
   smooth: boolean
@@ -11,6 +22,13 @@ export interface ScrollToOptions {
   targetPadding: number
 }
 
+/**
+ * For theme developers, you can use this function to scroll to the target element.
+ * For example, when you click the anchor link in the markdown file, it will scroll to the target element.
+ * @param el
+ * @param hash
+ * @param options
+ */
 export function scrollTo(el: HTMLElement, hash: string, options: Partial<ScrollToOptions> = {
   smooth: true,
   targetPadding: -64,

package/client/utils/time.ts

@@ -10,6 +10,14 @@ export function formatDate(date: string | number | Date, template = 'yyyy-MM-dd'
   return format(date, template)
 }
 
+/**
+ * date-fns format date with 'yyyy-MM-dd HH:mm:ss'
+ * @param date
+ */
+export function formatTimestamp(date: string | number | Date): string {
+  return format(date, 'yyyy-MM-dd HH:mm:ss')
+}
+
 /**
  * sort posts by date
  * @param posts