valaxy-theme-press 0.28.11 → 1.0.0-beta.2

package/README.md

@@ -1,15 +1,35 @@
 # valaxy-theme-press
 
-This is a theme for [valaxy docs](https://valaxy.site/).
+Documentation theme for [Valaxy](https://valaxy.site).
 
-Inspired by [vitepress](https://vitepress.dev).
+It is inspired by [VitePress](https://vitepress.dev), and it powers the Valaxy documentation site.
 
-我开发此主题以编写 Valaxy 的初期文档，同时以便发现 valaxy 编写主题中的痛点。
-它增加了 VitePress 此前默认所没有的一些功能，KaTeX、文章分类、单页 CSS i18n + Vue i18n、Vue Router、Pinia 状态管理，组件自动注册等。
+## Install
 
-- [预览](https://press.valaxy.site)
+```bash
+pnpm add valaxy-theme-press
+```
+
+```ts
+import type { PressTheme } from 'valaxy-theme-press'
+import { defineValaxyConfig } from 'valaxy'
+
+export default defineValaxyConfig<PressTheme.Config>({
+  theme: 'press',
+  themeConfig: {
+    logo: '/favicon.svg',
+  },
+})
+```
+
+## Links
+
+- [Documentation](https://valaxy.site/themes/press)
+- [中文文档](https://valaxy.site/zh/themes/press)
+- [Preview](https://press.valaxy.site)
+- [Source](https://github.com/YunYouJun/valaxy/tree/main/packages/valaxy-theme-press)
 
 ## Reference
 
-- [vitepress](https://vitepress.vuejs.org/)
+- [vitepress](https://vitepress.dev/)
 - [nextjs](https://nextjs.org/)

package/components/PressCategory.vue

@@ -1,9 +1,11 @@
 <script lang="ts" setup>
-import type { Category } from 'valaxy'
+import type { Category, CategoryList } from 'valaxy'
 import { isCategoryList, useValaxyI18n } from 'valaxy'
-import { ref } from 'vue'
+import { computed, ref } from 'vue'
 import { useI18n } from 'vue-i18n'
 
+type CategoryChild = CategoryList['children'] extends Map<string, infer T> ? T : never
+
 const props = withDefaults(defineProps<{
   // to eliminate the warning
   category: Category
@@ -16,54 +18,102 @@ const props = withDefaults(defineProps<{
   collapsable?: boolean
 }>(), {
   collapsable: true,
+  level: 0,
 })
 
-const collapsable = ref(props.collapsable)
+const collapsed = ref(props.collapsable)
+const hasChildren = computed(() => props.category.children.size > 0)
 const { t } = useI18n()
 const { $tO } = useValaxyI18n()
+
+function toggle() {
+  collapsed.value = !collapsed.value
+}
+
+function getCategoryItemKey(categoryItem: CategoryChild, index: number): string | number {
+  return isCategoryList(categoryItem)
+    ? categoryItem.name
+    : categoryItem.path || index
+}
 </script>
 
 <template>
   <li
     v-if="category.total"
-    p="t-2"
-    w="full" border="t t-$pr-c-divider-light"
-    class="press-sidebar-item category-list-item inline-flex items-center justify-between"
-    text-14px
-    tabindex="0"
+    class="press-category-item"
+    :class="[`level-${props.level}`, { collapsed }]"
   >
-    <span class="category-name" font="bold" m="l-1" @click="displayCategory ? displayCategory(category.name) : null">
-      {{ category.name === 'Uncategorized' ? t('category.uncategorized') : t(`category.${category.name}`) }}
-      <!-- <sup font="normal">[{{ category.total }}]</sup> -->
-    </span>
-    <button
-      tabindex="0" role="button" aria-label="toggle section"
-      class="caret folder-action inline-flex cursor-pointer"
-      text-base
-      @click="collapsable = !collapsable"
+    <div
+      p="t-2"
+      w="full" border="t t-$pr-c-divider-light"
+      class="press-sidebar-item category-list-item inline-flex items-center justify-between"
+      text-14px
     >
-      <div v-if="collapsable" i-ri-folder-add-line />
-      <div v-else i-ri-folder-reduce-line />
-    </button>
-  </li>
+      <span class="category-name" font="bold" m="l-1" @click="displayCategory ? displayCategory(category.name) : null">
+        {{ category.name === 'Uncategorized' ? t('category.uncategorized') : t(`category.${category.name}`) }}
+        <!-- <sup font="normal">[{{ category.total }}]</sup> -->
+      </span>
+      <button
+        v-if="hasChildren"
+        type="button"
+        aria-label="toggle section"
+        :aria-expanded="!collapsed"
+        class="caret"
+        @click.stop="toggle"
+      >
+        <span class="caret-icon" :class="{ open: !collapsed }" i-ri-arrow-right-s-line aria-hidden="true" />
+      </button>
+    </div>
 
-  <ul v-if="!collapsable">
-    <li v-for="categoryItem, i in category.children.values()" :key="i" class="post-list-item">
-      <template v-if="!isCategoryList(categoryItem)">
-        <RouterLink
-          v-if="categoryItem.title" :to="categoryItem.path || ''"
-          class="inline-flex items-center"
-        >
-          <span class="text ml-1" text="sm">{{ $tO(categoryItem.title) }}</span>
-        </RouterLink>
-      </template>
+    <ul v-if="hasChildren && !collapsed" class="items press-category-list press-sidebar-category-list">
+      <template v-for="(categoryItem, i) in category.children.values()" :key="getCategoryItemKey(categoryItem, i)">
+        <li v-if="!isCategoryList(categoryItem)" class="post-list-item">
+          <RouterLink
+            v-if="categoryItem.title" :to="categoryItem.path || ''"
+            class="inline-flex items-center"
+          >
+            <span class="text ml-1" text="sm">{{ $tO(categoryItem.title) }}</span>
+          </RouterLink>
+        </li>
 
-      <PressCategory v-else :category="categoryItem" :display-category="displayCategory" :collapsable="collapsable" />
-    </li>
-  </ul>
+        <PressCategory
+          v-else
+          :category="categoryItem"
+          :display-category="displayCategory"
+          :collapsable="collapsed"
+          :level="props.level + 1"
+        />
+      </template>
+    </ul>
+  </li>
 </template>
 
 <style lang="scss">
+.press-category-item,
+.press-category-list,
+.post-list-item {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+}
+
+.press-category-item.level-0 {
+  padding-bottom: 24px;
+}
+
+.press-category-item.collapsed.level-0 {
+  padding-bottom: 10px;
+}
+
+.press-category-item.level-1 > .press-category-list,
+.press-category-item.level-2 > .press-category-list,
+.press-category-item.level-3 > .press-category-list,
+.press-category-item.level-4 > .press-category-list,
+.press-category-item.level-5 > .press-category-list {
+  border-left: 1px solid var(--vp-c-divider);
+  padding-left: 16px;
+}
+
 .post-list-item {
   // align with vitepress
   a {

package/components/PressNotFoundVisual.vue

@@ -0,0 +1,177 @@
+<script setup lang="ts">
+withDefaults(defineProps<{
+  code?: string
+  label: string
+}>(), {
+  code: '404',
+})
+</script>
+
+<template>
+  <div class="not-found-visual" aria-hidden="true">
+    <div class="not-found-orbit">
+      <span class="not-found-satellite not-found-satellite-a" />
+      <span class="not-found-satellite not-found-satellite-b" />
+      <span class="not-found-satellite not-found-satellite-c" />
+      <span class="not-found-signal">{{ label }}</span>
+    </div>
+
+    <div class="not-found-code" :title="code" font="mono">
+      {{ code }}
+    </div>
+  </div>
+</template>
+
+<style lang="scss" scoped>
+.not-found-visual {
+  position: relative;
+  display: grid;
+  place-items: center;
+  min-height: clamp(280px, 42vw, 420px);
+  isolation: isolate;
+}
+
+.not-found-orbit {
+  position: absolute;
+  width: min(100%, 360px);
+  aspect-ratio: 1;
+  border: 1px solid color-mix(in srgb, var(--vp-c-brand-1) 26%, transparent);
+  border-radius: 50%;
+  background:
+    radial-gradient(circle at 50% 50%, color-mix(in srgb, var(--vp-c-brand-1) 18%, transparent) 0 2px, transparent 3px),
+    radial-gradient(circle at 18% 24%, color-mix(in srgb, #f59e0b 32%, transparent) 0 3px, transparent 4px),
+    radial-gradient(circle at 78% 30%, color-mix(in srgb, #14b8a6 30%, transparent) 0 2px, transparent 3px),
+    radial-gradient(circle at 72% 76%, color-mix(in srgb, #ef4444 28%, transparent) 0 3px, transparent 4px);
+  box-shadow:
+    inset 0 0 56px color-mix(in srgb, var(--vp-c-brand-1) 9%, transparent),
+    0 28px 80px color-mix(in srgb, var(--vp-c-brand-1) 12%, transparent);
+}
+
+.not-found-orbit::before,
+.not-found-orbit::after {
+  content: "";
+  position: absolute;
+  inset: 12%;
+  border: 1px dashed color-mix(in srgb, var(--vp-c-text-2) 22%, transparent);
+  border-radius: 50%;
+  transform: rotate(-22deg) scaleX(1.18);
+}
+
+.not-found-orbit::after {
+  inset: 25%;
+  transform: rotate(34deg) scaleX(1.35);
+  border-style: solid;
+  opacity: .55;
+}
+
+.not-found-satellite {
+  position: absolute;
+  width: 14px;
+  height: 14px;
+  border-radius: 50%;
+  box-shadow: 0 0 0 6px color-mix(in srgb, currentcolor 12%, transparent);
+}
+
+.not-found-satellite-a {
+  top: 18%;
+  left: 67%;
+  color: #f59e0b;
+}
+
+.not-found-satellite-b {
+  right: 15%;
+  bottom: 24%;
+  color: #14b8a6;
+}
+
+.not-found-satellite-c {
+  bottom: 18%;
+  left: 24%;
+  color: #ef4444;
+}
+
+.not-found-signal {
+  position: absolute;
+  right: 2%;
+  bottom: 10%;
+  max-width: 9rem;
+  padding: 6px 10px;
+  border: 1px solid var(--vp-c-divider);
+  border-radius: 8px;
+  background: var(--vp-c-bg);
+  color: var(--vp-c-text-2);
+  font-size: 12px;
+  line-height: 1.4;
+  box-shadow: 0 12px 32px rgb(0 0 0 / .08);
+}
+
+.not-found-code {
+  position: relative;
+  z-index: 1;
+  color: var(--vp-c-text-1);
+  font-size: clamp(6.5rem, 18vw, 13rem);
+  font-weight: 900;
+  line-height: .82;
+  letter-spacing: 0;
+  text-shadow:
+    0 1px 0 var(--vp-c-bg),
+    0 14px 34px rgb(0 0 0 / .18);
+}
+
+@media (max-width: 767px) {
+  .not-found-visual {
+    min-height: clamp(132px, 24svh, 205px);
+  }
+
+  .not-found-orbit {
+    width: min(56vw, 200px, 28svh);
+  }
+
+  .not-found-code {
+    font-size: clamp(4.5rem, 22vw, 6.25rem);
+  }
+
+  .not-found-signal {
+    right: 0;
+  }
+}
+
+@media (max-width: 767px) and (max-height: 700px) {
+  .not-found-visual {
+    min-height: clamp(104px, 21svh, 150px);
+  }
+
+  .not-found-orbit {
+    width: min(46vw, 160px, 24svh);
+  }
+
+  .not-found-signal {
+    display: none;
+  }
+}
+
+@media (prefers-reduced-motion: no-preference) {
+  .not-found-satellite-a {
+    animation: not-found-float 5s ease-in-out infinite;
+  }
+
+  .not-found-satellite-b {
+    animation: not-found-float 6s ease-in-out .8s infinite;
+  }
+
+  .not-found-satellite-c {
+    animation: not-found-float 5.5s ease-in-out .35s infinite;
+  }
+}
+
+@keyframes not-found-float {
+  0%,
+  100% {
+    transform: translate3d(0, 0, 0);
+  }
+
+  50% {
+    transform: translate3d(0, -10px, 0);
+  }
+}
+</style>

package/components/PressSidebar.vue

@@ -1,14 +1,18 @@
 <script lang="ts" setup>
 import type { CategoryList, Post } from 'valaxy'
+import type { PressTheme } from '../types'
 import { removeItemFromCategory, usePageList, useSidebar } from 'valaxy'
 import { computed } from 'vue'
+import { useRoute } from 'vue-router'
 import { useLocaleConfig } from '../composables'
+import { getSidebar, getSidebarGroups, isSidebarItem } from '../utils/sidebar'
 
 defineProps<{
   open: boolean
 }>()
 
 const pages = usePageList()
+const route = useRoute()
 const { localeConfig, currentLocaleKey, hasLocales, currentLocale } = useLocaleConfig()
 
 /**
@@ -34,6 +38,29 @@ const localePages = computed(() => {
 
 const sidebar = computed(() => localeConfig.value.sidebar)
 
+const sidebarItems = computed(() => getSidebar(sidebar.value, route.path))
+
+const sidebarGroups = computed(() => {
+  return getSidebarGroups(sidebarItems.value)
+})
+
+const renderGroups = computed(() => {
+  return sidebarGroups.value.map((group, index) => {
+    const groupItem = group.text || group.link
+      ? { ...group, items: group.items.filter(isSidebarItem) }
+      : undefined
+
+    return {
+      key: group.text || group.link || index,
+      groupItem,
+      items: groupItem ? [] : group.items,
+    }
+  })
+})
+
+// Explicit groups and generated categories share the same root visual depth.
+const sidebarGroupDepth = 0
+
 /**
  * Build categories from locale-filtered pages.
  * Fully reactive: recomputes when route/locale changes.
@@ -103,9 +130,8 @@ const categories = computed(() => {
 
   // Remove categories not listed in sidebar config
   removeItemFromCategory(categoryList, 'Uncategorized')
-  const sidebarVal = localeConfig.value.sidebar
-  if (Array.isArray(sidebarVal)) {
-    const sidebarNames = sidebarVal.filter((item): item is string => typeof item === 'string')
+  if (sidebarItems.value.length) {
+    const sidebarNames = sidebarItems.value.filter((item): item is string => typeof item === 'string')
     categoryList.children.forEach((_val, key) => {
       if (!sidebarNames.includes(key))
         removeItemFromCategory(categoryList, key)
@@ -116,31 +142,63 @@ const categories = computed(() => {
 })
 
 const { hasSidebar } = useSidebar()
+
+const shouldShowSidebar = computed(() => {
+  return hasSidebar.value && sidebarGroups.value.length > 0
+})
+
+function getSidebarItemKey(item: PressTheme.SidebarEntry, index: number): string | number {
+  if (typeof item === 'string')
+    return item
+  return item.text || item.link || index
+}
+
+function getSidebarRootItemClasses(groupIndex: number, itemIndex = 0) {
+  return [
+    'press-sidebar-root-item',
+    { 'is-separated': groupIndex > 0 || itemIndex > 0 },
+  ]
+}
 </script>
 
 <template>
   <aside
-    v-if="hasSidebar"
+    v-if="shouldShowSidebar"
     class="press-sidebar shadow-lg" :class="{ open }"
     @click.stop
   >
-    <div text="left" m="2">
-      <ul v-for="item in sidebar" :key="item" class="category-list">
-        <template v-if="typeof item === 'string'">
-          <PressCategoryByName
-            :categories="categories"
-            :item="item"
-          />
-        </template>
+    <nav
+      id="pr-sidebar-nav"
+      class="press-sidebar-nav"
+      aria-label="Sidebar Navigation"
+      text="left"
+      m="2"
+    >
+      <ul v-for="(group, groupIndex) in renderGroups" :key="group.key" class="press-sidebar-list category-list">
         <PressSidebarItem
-          v-else
-          p="t-2"
-          border="t t-$pr-c-divider-light"
-          :item="item"
-          :depth="0"
+          v-if="group.groupItem"
+          :class="getSidebarRootItemClasses(groupIndex)"
+          :item="group.groupItem"
+          :depth="sidebarGroupDepth"
         />
+        <template v-else>
+          <template v-for="(item, index) in group.items" :key="getSidebarItemKey(item, index)">
+            <PressCategoryByName
+              v-if="typeof item === 'string'"
+              :class="getSidebarRootItemClasses(groupIndex, index)"
+              :categories="categories"
+              :item="item"
+            />
+            <PressSidebarItem
+              v-else
+              :class="getSidebarRootItemClasses(groupIndex, index)"
+              :item="item"
+              :depth="0"
+            />
+          </template>
+        </template>
       </ul>
-    </div>
+    </nav>
   </aside>
 </template>
 
@@ -189,6 +247,24 @@ const { hasSidebar } = useSidebar()
   }
 }
 
+.press-sidebar-list {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+}
+
+.press-sidebar-root-item.is-separated {
+  border-top: 1px solid var(--pr-c-divider-light);
+}
+
+.press-sidebar-root-item > .press-sidebar-item {
+  padding-top: 0.5rem;
+}
+
+.press-sidebar-root-item > .category-list-item {
+  border-top: 0;
+}
+
 .category-list {
   &:first-child {
     .category-list-item {
@@ -211,6 +287,16 @@ const { hasSidebar } = useSidebar()
     flex-shrink: 0;
   }
 
+  .caret-icon {
+    width: 18px;
+    height: 18px;
+    transition: transform var(--va-transition-duration);
+
+    &.open {
+      transform: rotate(90deg);
+    }
+  }
+
   &:hover .caret {
     color: var(--vp-c-text-2);
   }
@@ -219,8 +305,4 @@ const { hasSidebar } = useSidebar()
     color: var(--vp-c-text-1);
   }
 }
-
-.category-list+.category-list {
-  margin-top: 1rem;
-}
 </style>

package/components/PressSidebarItem.vue

@@ -19,8 +19,6 @@ const {
   toggle,
 } = useSidebarControl(computed(() => props.item))
 
-const sectionTag = computed(() => (hasChildren.value ? 'section' : `div`))
-
 const linkTag = computed(() => (isLink.value ? 'a' : 'div'))
 
 const textTag = computed(() => {
@@ -31,7 +29,13 @@ const textTag = computed(() => {
       : `h${props.depth + 2}`
 })
 
-const itemRole = computed(() => (isLink.value ? undefined : 'button'))
+const rawText = computed(() => props.item.text || '')
+
+const childItems = computed(() => props.item.items || [])
+
+const hasChildItems = computed(() => childItems.value.length > 0)
+
+const hasCaret = computed(() => collapsible.value && hasChildItems.value)
 
 const classes = computed(() => [
   [`level-${props.depth}`],
@@ -42,6 +46,8 @@ const classes = computed(() => [
   { 'has-active': hasActiveLink.value },
 ])
 
+const itemRole = computed(() => (hasCaret.value && !isLink.value ? 'button' : undefined))
+
 function onItemInteraction(e: MouseEvent | Event) {
   if ('key' in e && e.key !== 'Enter')
     return
@@ -49,27 +55,28 @@ function onItemInteraction(e: MouseEvent | Event) {
   !props.item.link && toggle()
 }
 
-function onCaretClick() {
-  props.item.link && toggle()
-}
-
 const { t } = useI18n()
 
-const htmlText = computed(() => t(props.item.text || ''))
+const htmlText = computed(() => {
+  return t(rawText.value) || rawText.value
+})
+
+function getChildItemKey(item: DefaultTheme.SidebarItem, index: number): string | number {
+  return item.text || item.link || index
+}
 </script>
 
 <template>
-  <component
-    :is="sectionTag"
-    class="VPSidebarItem" :class="classes"
+  <li
+    class="VPSidebarItem press-sidebar-item-node" :class="classes"
   >
     <div
-      v-if="item.text"
+      v-if="rawText"
       class="press-sidebar-item item"
       :role="itemRole"
-      :tabindex="item.items && 0"
+      :tabindex="hasCaret && !props.item.link ? 0 : undefined"
       v-on="
-        item.items
+        hasCaret && !props.item.link
           ? { click: onItemInteraction, keydown: onItemInteraction }
           : {}
       "
@@ -77,47 +84,57 @@ const htmlText = computed(() => t(props.item.text || ''))
       <div class="indicator" />
 
       <AppLink
-        v-if="item.link"
+        v-if="props.item.link"
         :tag="linkTag"
         class="link"
-        :href="item.link"
-        :rel="item.rel"
-        :target="item.target"
+        :href="props.item.link"
+        :rel="props.item.rel"
+        :target="props.item.target"
       >
-        <!-- eslint-disable-next-line vue/no-v-text-v-html-on-component -->
-        <component :is="textTag" class="text ml-1" v-html="htmlText" />
+        <component :is="textTag" class="text ml-1">
+          <span v-html="htmlText" />
+        </component>
       </AppLink>
-      <!-- eslint-disable-next-line vue/no-v-text-v-html-on-component -->
-      <component :is="textTag" v-else class="text ml-1" v-html="htmlText" />
+      <component :is="textTag" v-else class="text ml-1">
+        <span v-html="htmlText" />
+      </component>
 
       <button
-        v-if="item.collapsed != null && item.items"
-        tabindex="0" role="button" aria-label="toggle section"
-        class="caret folder-action inline-flex cursor-pointer"
-        @click="onCaretClick" @keydown.enter="onCaretClick"
+        v-if="hasCaret"
+        type="button"
+        aria-label="toggle section"
+        :aria-expanded="!collapsed"
+        class="caret"
+        @click.stop="toggle"
       >
-        <div v-if="collapsed" i-ri-folder-add-line />
-        <div v-else i-ri-folder-reduce-line />
+        <span class="caret-icon" :class="{ open: !collapsed }" i-ri-arrow-right-s-line aria-hidden="true" />
       </button>
     </div>
 
-    <div v-if="item.items && item.items.length" class="items">
+    <ul v-if="hasChildItems" class="items press-sidebar-item-list">
       <template v-if="depth < 5">
         <PressSidebarItem
-          v-for="i in item.items"
-          :key="i.text"
+          v-for="(i, index) in childItems"
+          :key="getChildItemKey(i, index)"
           :item="i"
           :depth="depth + 1"
         />
       </template>
-    </div>
-  </component>
+    </ul>
+  </li>
 </template>
 
 <style scoped>
-/* .VPSidebarItem.level-0 {
+.press-sidebar-item-node,
+.press-sidebar-item-list {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+}
+
+.VPSidebarItem.level-0 {
   padding-bottom: 24px;
-} */
+}
 
 .VPSidebarItem.collapsed.level-0 {
   padding-bottom: 10px;

package/composables/prev-next.ts

@@ -4,6 +4,7 @@ import { isCategoryList, removeItemFromCategory, useFrontmatter, usePageList, us
 import { computed } from 'vue'
 import { useI18n } from 'vue-i18n'
 import { useRoute } from 'vue-router'
+import { getSidebar } from '../utils/sidebar'
 import { useLocaleConfig } from './locale'
 import { normalize } from './sidebar'
 
@@ -109,70 +110,6 @@ function getCategoryLinks(categoryTree: CategoryList, categoryName: string, reso
   return links
 }
 
-/**
- * Resolve sidebar items for the current route path from the theme config.
- */
-function getSidebarItems(
-  sidebar: PressTheme.Sidebar | undefined,
-  path: string,
-): PressTheme.SidebarItem[] {
-  if (!sidebar)
-    return []
-
-  if (Array.isArray(sidebar)) {
-    // Sidebar arrays may contain strings (category names) — filter to objects only
-    const items = sidebar.filter((item): item is PressTheme.SidebarItem => typeof item !== 'string')
-    return addBase(items)
-  }
-
-  // SidebarMulti: find the longest matching prefix
-  path = ensureStartingSlash(path)
-  const dir = Object.keys(sidebar)
-    .sort((a, b) => b.split('/').length - a.split('/').length)
-    .find((dir) => {
-      const normalizedDir = ensureStartingSlash(dir)
-      // Ensure boundary match: dir must end with '/' or path must have '/' after dir
-      const dirWithSlash = normalizedDir.endsWith('/') ? normalizedDir : `${normalizedDir}/`
-      return path.startsWith(dirWithSlash) || path === normalizedDir
-    })
-
-  if (!dir)
-    return []
-
-  const matched = sidebar[dir]
-  if (Array.isArray(matched)) {
-    const items = matched.filter((item): item is PressTheme.SidebarItem => typeof item !== 'string')
-    return addBase(items)
-  }
-
-  return addBase(matched.items, matched.base)
-}
-
-function ensureStartingSlash(path: string): string {
-  return path.startsWith('/') ? path : `/${path}`
-}
-
-/**
- * Join base and link with exactly one `/` separator.
- */
-function joinPath(base: string, link: string): string {
-  const normalizedBase = base.endsWith('/') ? base.slice(0, -1) : base
-  const normalizedLink = link.startsWith('/') ? link : `/${link}`
-  return normalizedBase + normalizedLink
-}
-
-function addBase(items: PressTheme.SidebarItem[], base?: string): PressTheme.SidebarItem[] {
-  return items.map((item) => {
-    const result = { ...item }
-    const itemBase = result.base || base
-    if (itemBase && result.link)
-      result.link = joinPath(itemBase, result.link)
-    if (result.items)
-      result.items = addBase(result.items, itemBase)
-    return result
-  })
-}
-
 interface FlatLink {
   text: string
   link: string
@@ -251,29 +188,17 @@ export function usePrevNext() {
   })
 
   return computed(() => {
-    const sidebar = localeConfig.value.sidebar
-    let candidates: FlatLink[]
-
-    if (Array.isArray(sidebar)) {
-      // Build category tree from locale-filtered pages
-      const categoryTree = buildCategoryTree(localePages.value)
-
-      // Walk sidebar items in order, expanding string categories into page links
-      candidates = []
-      for (const item of sidebar) {
-        if (typeof item === 'string') {
-          // Expand category name into its page links
-          candidates.push(...getCategoryLinks(categoryTree, item, resolveTitle))
-        }
-        else {
-          // Object sidebar item — flatten as before
-          candidates.push(...getFlatLinks(addBase([item]), t))
-        }
+    const categoryTree = buildCategoryTree(localePages.value)
+    const sidebarItems = getSidebar(localeConfig.value.sidebar, route.path)
+    const candidates: FlatLink[] = []
+
+    for (const item of sidebarItems) {
+      if (typeof item === 'string') {
+        candidates.push(...getCategoryLinks(categoryTree, item, resolveTitle))
+        continue
       }
-    }
-    else {
-      // SidebarMulti — only object items, use original logic
-      candidates = getFlatLinks(getSidebarItems(sidebar, route.path), t)
+
+      candidates.push(...getFlatLinks([item], t))
     }
 
     const index = candidates.findIndex(link =>

package/composables/sidebar.ts

@@ -38,7 +38,7 @@ export function isActive(
   if (matchPath === undefined)
     return false
 
-  currentPath = normalize(`/${currentPath}`)
+  currentPath = normalize(currentPath.startsWith('/') ? currentPath : `/${currentPath}`)
 
   if (asRegex)
     return new RegExp(matchPath).test(currentPath)

package/layouts/404.vue

@@ -1,34 +1,280 @@
 <script lang="ts" setup>
+import { useBack } from 'valaxy'
+import { computed } from 'vue'
 import { useI18n } from 'vue-i18n'
-import { useRouter } from 'vue-router'
+import { useRoute } from 'vue-router'
+import PressNotFoundVisual from '../components/PressNotFoundVisual.vue'
 
-const router = useRouter()
-const { t } = useI18n()
+type NotFoundLocale = 'en' | 'zh'
+
+const route = useRoute()
+const { locale } = useI18n()
+const { back } = useBack()
+
+const messages = {
+  en: {
+    eyebrow: 'Lost route',
+    title: 'This page drifted out of orbit.',
+    description: 'The address you opened does not match a page in this site. Check the path, return to the last page, or restart from the home page.',
+    currentPath: 'Current path',
+    back: 'Go back',
+    home: 'Home',
+    orbit: 'Route signal',
+  },
+  zh: {
+    eyebrow: '路线迷航',
+    title: '这个页面暂时偏离了轨道。',
+    description: '当前地址没有匹配到站点页面。你可以检查路径，返回上一页，或从首页重新出发。',
+    currentPath: '当前路径',
+    back: '返回上一页',
+    home: '回到首页',
+    orbit: '路由信号',
+  },
+} as const
+
+const currentLocale = computed<NotFoundLocale>(
+  () => locale.value.startsWith('zh') || route.path.startsWith('/zh') ? 'zh' : 'en',
+)
+
+const content = computed(() => messages[currentLocale.value])
+const currentPath = computed(() => route.fullPath || route.path)
+const homeLink = computed(() => currentLocale.value === 'zh' ? '/zh/' : '/')
 </script>
 
 <template>
-  <Layout>
-    <template #sidebar>
-      <div />
-    </template>
-    <div text="center" m="t-20">
-      <div class="not-found" title="404" font="mono">
-        404
-      </div>
-
-      <RouterView />
-      <div>
-        <button btn text-sm m="3 t8" @click="router.back()">
-          {{ t('button.back') }}
-        </button>
-      </div>
-    </div>
-  </Layout>
+  <div class="layout antialiased not-found-layout">
+    <PressNav />
+    <main class="not-found-shell">
+      <section class="not-found-panel" aria-labelledby="not-found-title">
+        <PressNotFoundVisual :label="content.orbit" />
+
+        <div class="not-found-copy">
+          <div class="not-found-toolbar">
+            <p class="not-found-eyebrow">
+              <span i-ri-compass-3-line aria-hidden="true" />
+              {{ content.eyebrow }}
+            </p>
+          </div>
+
+          <h1 id="not-found-title" class="not-found-title">
+            {{ content.title }}
+          </h1>
+
+          <p class="not-found-description">
+            {{ content.description }}
+          </p>
+
+          <p class="not-found-path">
+            <span>{{ content.currentPath }}</span>
+            <code>{{ currentPath }}</code>
+          </p>
+
+          <div class="not-found-actions">
+            <button type="button" class="not-found-action primary" @click="back">
+              <span i-ri-arrow-left-line aria-hidden="true" />
+              {{ content.back }}
+            </button>
+
+            <AppLink class="not-found-action secondary" :href="homeLink">
+              <span i-ri-home-4-line aria-hidden="true" />
+              {{ content.home }}
+            </AppLink>
+          </div>
+        </div>
+      </section>
+    </main>
+  </div>
 </template>
 
 <style lang="scss" scoped>
-.not-found {
-  font-size: 10rem;
-  text-shadow: 0 5px 10px rgb(0 0 0 / .25), 0 20px 20px rgb(0 0 0 / .15);
+.not-found-layout {
+  min-height: 100svh;
+  overflow: hidden;
+}
+
+.not-found-shell {
+  min-height: 100svh;
+  box-sizing: border-box;
+  display: grid;
+  place-items: center;
+  overflow: hidden;
+  padding: calc(var(--pr-nav-height) + clamp(16px, 3vw, 28px)) clamp(18px, 5vw, 72px) clamp(20px, 4vw, 40px);
+}
+
+.not-found-panel {
+  width: min(100%, 1040px);
+  max-height: calc(100svh - var(--pr-nav-height) - clamp(36px, 7vw, 68px));
+  display: grid;
+  grid-template-columns: minmax(280px, .9fr) minmax(0, 1fr);
+  align-items: center;
+  gap: clamp(28px, 6vw, 72px);
+}
+
+.not-found-copy {
+  min-width: 0;
+}
+
+.not-found-toolbar {
+  display: flex;
+  align-items: center;
+  margin-bottom: 18px;
+}
+
+.not-found-eyebrow {
+  display: inline-flex;
+  align-items: center;
+  gap: 8px;
+  margin: 0;
+  color: var(--vp-c-brand-1);
+  font-size: 14px;
+  font-weight: 700;
+}
+
+.not-found-title {
+  max-width: 12ch;
+  margin: 0;
+  color: var(--vp-c-text-1);
+  font-size: clamp(2.25rem, 6vw, 4.75rem);
+  line-height: .98;
+  letter-spacing: 0;
+}
+
+.not-found-description {
+  max-width: 42rem;
+  margin: 18px 0 0;
+  color: var(--vp-c-text-2);
+  font-size: clamp(1rem, 2vw, 1.125rem);
+  line-height: 1.7;
+}
+
+.not-found-path {
+  display: grid;
+  gap: 8px;
+  max-width: 100%;
+  margin: 20px 0 0;
+  padding: 12px 16px;
+  border: 1px solid var(--vp-c-divider);
+  border-radius: 8px;
+  background: color-mix(in srgb, var(--vp-c-bg-soft) 72%, transparent);
+  color: var(--vp-c-text-2);
+  font-size: 13px;
+}
+
+.not-found-path code {
+  display: block;
+  max-width: 100%;
+  overflow-wrap: anywhere;
+  color: var(--vp-c-text-1);
+  font-size: 14px;
+}
+
+.not-found-actions {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 12px;
+  margin-top: 22px;
+}
+
+.not-found-action {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  gap: 8px;
+  min-height: 42px;
+  padding: 0 18px;
+  border: 1px solid transparent;
+  border-radius: 999px;
+  font-size: 14px;
+  font-weight: 700;
+  text-decoration: none;
+  cursor: pointer;
+  transition: transform var(--va-transition-duration), border-color var(--va-transition-duration), background-color var(--va-transition-duration), color var(--va-transition-duration), box-shadow var(--va-transition-duration);
+}
+
+.not-found-action:hover {
+  transform: translateY(-1px);
+}
+
+.not-found-action.primary {
+  background: var(--vp-c-brand-1);
+  color: var(--vp-c-white);
+  box-shadow: 0 12px 28px color-mix(in srgb, var(--vp-c-brand-1) 24%, transparent);
+}
+
+.not-found-action.secondary {
+  border-color: var(--vp-c-divider);
+  background: var(--vp-c-bg);
+  color: var(--vp-c-text-1);
+}
+
+@media (max-width: 767px) {
+  .not-found-layout {
+    height: 100svh;
+    display: flex;
+    flex-direction: column;
+  }
+
+  .not-found-shell {
+    flex: 1;
+    min-height: 0;
+    padding: clamp(8px, 2.4svh, 16px) clamp(18px, 5vw, 24px) clamp(12px, 3svh, 20px);
+  }
+
+  .not-found-panel {
+    max-height: 100%;
+    grid-template-columns: 1fr;
+    align-content: center;
+    gap: clamp(8px, 1.6svh, 14px);
+  }
+
+  .not-found-toolbar {
+    margin-bottom: clamp(8px, 1.8svh, 14px);
+  }
+
+  .not-found-title {
+    max-width: 13ch;
+    font-size: clamp(1.75rem, 8.5vw, 2.75rem);
+    line-height: 1;
+  }
+
+  .not-found-description {
+    margin-top: clamp(8px, 1.6svh, 12px);
+    font-size: clamp(.88rem, 3.8vw, 1rem);
+    line-height: 1.55;
+  }
+
+  .not-found-path {
+    gap: 6px;
+    margin-top: clamp(10px, 1.8svh, 14px);
+    padding: 10px 14px;
+  }
+
+  .not-found-path code {
+    font-size: 13px;
+  }
+
+  .not-found-actions,
+  .not-found-action {
+    width: 100%;
+  }
+
+  .not-found-actions {
+    gap: 8px;
+    margin-top: clamp(10px, 2svh, 16px);
+  }
+
+  .not-found-action {
+    min-height: 38px;
+  }
+}
+
+@media (max-width: 767px) and (max-height: 700px) {
+  .not-found-path {
+    display: none;
+  }
+
+  .not-found-description {
+    max-width: 34rem;
+  }
 }
 </style>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "valaxy-theme-press",
-  "version": "0.28.11",
+  "version": "1.0.0-beta.2",
   "description": "Docs (VitePress-like) theme for Valaxy",
   "author": {
     "email": "me@yunyoujun.cn",
@@ -33,10 +33,10 @@
     "@docsearch/css": "^4.6.3",
     "@docsearch/js": "^4.6.3",
     "@docsearch/sidepanel-js": "^4.6.3",
-    "reka-ui": "^2.9.7",
+    "reka-ui": "^2.10.1",
     "vitepress": "^2.0.0-alpha.17"
   },
   "devDependencies": {
-    "valaxy": "0.28.11"
+    "valaxy": "1.0.0-beta.2"
   }
 }

package/types/index.d.ts

@@ -4,8 +4,6 @@ export * from '../composables'
 export * from './home.d'
 
 export namespace PressTheme {
-  export type Sidebar = any
-
   export interface Footer {
     message?: string
     copyright?: string
@@ -32,9 +30,10 @@ export namespace PressTheme {
     text?: string
   }
 
-  export type Sidebar = SidebarItem[] | SidebarMulti
+  export type SidebarEntry = string | SidebarItem
+  export type Sidebar = SidebarEntry[] | SidebarMulti
   export interface SidebarMulti {
-    [path: string]: SidebarItem[] | { items: SidebarItem[], base: string }
+    [path: string]: SidebarEntry[] | { items: SidebarEntry[], base?: string }
   }
   export interface SidebarItem {
     /**

package/utils/sidebar.ts

@@ -0,0 +1,89 @@
+import type { PressTheme } from '../types'
+
+export interface SidebarGroup extends Omit<PressTheme.SidebarItem, 'items'> {
+  items: PressTheme.SidebarEntry[]
+}
+
+/**
+ * Resolve the sidebar for the current path.
+ *
+ * This follows VitePress' default theme behavior: arrays are used as-is,
+ * multi-sidebars use the longest matching path prefix, and object entries can
+ * provide a shared `base` for child links.
+ */
+export function getSidebar(sidebar: PressTheme.Sidebar | undefined, path: string): PressTheme.SidebarEntry[] {
+  if (Array.isArray(sidebar))
+    return addBase(sidebar)
+
+  if (!sidebar)
+    return []
+
+  const normalizedPath = ensureStartingSlash(path)
+  const dir = Object.keys(sidebar)
+    .sort((a, b) => b.split('/').length - a.split('/').length)
+    .find(dir => normalizedPath.startsWith(ensureStartingSlash(dir)))
+
+  const matched = dir ? sidebar[dir] : []
+
+  return Array.isArray(matched)
+    ? addBase(matched)
+    : addBase(matched.items, matched.base)
+}
+
+/**
+ * Convert resolved sidebar entries into renderable groups.
+ *
+ * Explicit groups with `items` are kept as groups. Consecutive top-level links
+ * or category names are grouped into an anonymous group, matching VitePress'
+ * sidebar rendering model.
+ */
+export function getSidebarGroups(sidebar: PressTheme.SidebarEntry[]): SidebarGroup[] {
+  const groups: SidebarGroup[] = []
+  let lastGroupIndex = 0
+
+  for (const item of sidebar) {
+    if (isSidebarItem(item) && item.items) {
+      groups.push({
+        ...item,
+        items: item.items,
+      })
+      lastGroupIndex = groups.length
+      continue
+    }
+
+    if (!groups[lastGroupIndex])
+      groups.push({ items: [] })
+
+    groups[lastGroupIndex].items.push(item)
+  }
+
+  return groups
+}
+
+export function isSidebarItem(item: PressTheme.SidebarEntry): item is PressTheme.SidebarItem {
+  return typeof item !== 'string'
+}
+
+function ensureStartingSlash(path: string): string {
+  return path.startsWith('/') ? path : `/${path}`
+}
+
+function addBase(items: PressTheme.SidebarEntry[], base?: string): PressTheme.SidebarEntry[] {
+  return items.map(item => addBaseToItem(item, base))
+}
+
+function addBaseToItem(item: PressTheme.SidebarEntry, base?: string): PressTheme.SidebarEntry {
+  if (!isSidebarItem(item))
+    return item
+
+  const result = { ...item }
+  const itemBase = result.base || base
+
+  if (itemBase && result.link)
+    result.link = itemBase + result.link.replace(/^\//, itemBase.endsWith('/') ? '' : '/')
+
+  if (result.items)
+    result.items = addBase(result.items, itemBase).filter(isSidebarItem)
+
+  return result
+}