feat(components): add navigation context provider and enhance footer navigation

Added NavigationContext provider to enable navigation functionality throughout the component tree. Enhanced the navigation footer with improved styling and behavior for both previous and next buttons, including hover effects and proper state management. This change improves the overall navigation experience by providing consistent access to navigation functions and better visual feedback for users interacting with the navigation controls.

Author: tt-a1i

src/components/PageLayout.tsx

@@ -2,6 +2,7 @@ import { useCallback, useEffect, useMemo, useState, type ReactNode } from 'react
 import { flatNavItems } from '../nav';
 import { useOutline } from './OutlineContext';
 import { OutlineProvider } from './OutlineProvider';
+import { NavigationContext } from '../contexts/NavigationContext';
 
 function BackToTop() {
   const [visible, setVisible] = useState(false);
@@ -232,49 +233,53 @@ export function PageLayout({
     setActiveSectionId(id);
   }, []);
 
+  const navigationValue = useMemo(() => ({ navigate: onNavigate }), [onNavigate]);
+
   return (
-    <OutlineProvider key={activeTab}>
-      <BackToTop />
-      <OutlineHeader
-        activeSectionId={activeSectionId}
-        setActiveSectionId={setActiveSectionId}
-        onSelectSection={onSelectSection}
-      />
-      {children}
-
-      {/* Navigation Footer */}
-      <div className="mt-12 pt-6 border-t border-[var(--border-subtle)]">
-        <div className="flex items-center justify-between gap-4">
-          <button
-            disabled={!prev}
-            onClick={() => prev && onNavigate(prev.id)}
-            className={`group flex items-center gap-2 px-4 py-2.5 rounded-md text-sm font-mono border transition-all duration-200 ${
-              prev
-                ? 'bg-[var(--bg-panel)] border-[var(--border-subtle)] text-[var(--text-secondary)] hover:bg-[var(--bg-elevated)] hover:border-[var(--cyber-blue-dim)] hover:text-[var(--cyber-blue)]'
-                : 'bg-[var(--bg-void)] border-[var(--border-subtle)] text-[var(--text-muted)] cursor-not-allowed opacity-50'
-            }`}
-          >
-            <span className={`transition-transform duration-200 ${prev ? 'group-hover:-translate-x-1' : ''}`}>←</span>
-            <span className="max-w-[120px] truncate">{prev ? prev.label : 'EOF'}</span>
-          </button>
-          <div className="text-xs text-[var(--text-muted)] font-mono hidden sm:block">
-            // navigate
+    <NavigationContext.Provider value={navigationValue}>
+      <OutlineProvider key={activeTab}>
+        <BackToTop />
+        <OutlineHeader
+          activeSectionId={activeSectionId}
+          setActiveSectionId={setActiveSectionId}
+          onSelectSection={onSelectSection}
+        />
+        {children}
+
+        {/* Navigation Footer */}
+        <div className="mt-12 pt-6 border-t border-[var(--border-subtle)]">
+          <div className="flex items-center justify-between gap-4">
+            <button
+              disabled={!prev}
+              onClick={() => prev && onNavigate(prev.id)}
+              className={`group flex items-center gap-2 px-4 py-2.5 rounded-md text-sm font-mono border transition-all duration-200 ${
+                prev
+                  ? 'bg-[var(--bg-panel)] border-[var(--border-subtle)] text-[var(--text-secondary)] hover:bg-[var(--bg-elevated)] hover:border-[var(--cyber-blue-dim)] hover:text-[var(--cyber-blue)]'
+                  : 'bg-[var(--bg-void)] border-[var(--border-subtle)] text-[var(--text-muted)] cursor-not-allowed opacity-50'
+              }`}
+            >
+              <span className={`transition-transform duration-200 ${prev ? 'group-hover:-translate-x-1' : ''}`}>←</span>
+              <span className="max-w-[120px] truncate">{prev ? prev.label : 'EOF'}</span>
+            </button>
+            <div className="text-xs text-[var(--text-muted)] font-mono hidden sm:block">
+              // navigate
+            </div>
+            <button
+              disabled={!next}
+              onClick={() => next && onNavigate(next.id)}
+              className={`group flex items-center gap-2 px-4 py-2.5 rounded-md text-sm font-mono border transition-all duration-200 ${
+                next
+                  ? 'bg-[var(--bg-panel)] border-[var(--border-subtle)] text-[var(--text-secondary)] hover:bg-[var(--bg-elevated)] hover:border-[var(--terminal-green-dim)] hover:text-[var(--terminal-green)]'
+                  : 'bg-[var(--bg-void)] border-[var(--border-subtle)] text-[var(--text-muted)] cursor-not-allowed opacity-50'
+              }`}
+            >
+              <span className="max-w-[120px] truncate">{next ? next.label : 'EOF'}</span>
+              <span className={`transition-transform duration-200 ${next ? 'group-hover:translate-x-1' : ''}`}>→</span>
+            </button>
           </div>
-          <button
-            disabled={!next}
-            onClick={() => next && onNavigate(next.id)}
-            className={`group flex items-center gap-2 px-4 py-2.5 rounded-md text-sm font-mono border transition-all duration-200 ${
-              next
-                ? 'bg-[var(--bg-panel)] border-[var(--border-subtle)] text-[var(--text-secondary)] hover:bg-[var(--bg-elevated)] hover:border-[var(--terminal-green-dim)] hover:text-[var(--terminal-green)]'
-                : 'bg-[var(--bg-void)] border-[var(--border-subtle)] text-[var(--text-muted)] cursor-not-allowed opacity-50'
-            }`}
-          >
-            <span className="max-w-[120px] truncate">{next ? next.label : 'EOF'}</span>
-            <span className={`transition-transform duration-200 ${next ? 'group-hover:translate-x-1' : ''}`}>→</span>
-          </button>
         </div>
-      </div>
-    </OutlineProvider>
+      </OutlineProvider>
+    </NavigationContext.Provider>
   );
 }
 

src/components/PageLink.tsx

@@ -0,0 +1,45 @@
+import { type ReactNode } from 'react';
+import { useNavigation } from '../contexts/NavigationContext';
+
+interface PageLinkProps {
+  /** 目标页面的 tab ID */
+  to: string;
+  /** 链接文本或子元素 */
+  children: ReactNode;
+  /** 额外的 className */
+  className?: string;
+  /** 自定义样式 */
+  style?: React.CSSProperties;
+}
+
+/**
+ * 跨页面导航链接组件。
+ *
+ * 使用此组件代替 `<a href="#xxx">` 来实现真正的页面切换。
+ *
+ * @example
+ * ```tsx
+ * <PageLink to="token-accounting">Token 计费系统</PageLink>
+ * ```
+ */
+export function PageLink({ to, children, className, style }: PageLinkProps) {
+  const { navigate } = useNavigation();
+
+  return (
+    <button
+      onClick={() => navigate(to)}
+      className={className}
+      style={{
+        cursor: 'pointer',
+        background: 'none',
+        border: 'none',
+        padding: 0,
+        font: 'inherit',
+        textAlign: 'inherit',
+        ...style,
+      }}
+    >
+      {children}
+    </button>
+  );
+}

src/components/RelatedPages.tsx

@@ -0,0 +1,38 @@
+interface RelatedPage {
+  id: string;
+  label: string;
+  description?: string;
+}
+
+interface RelatedPagesProps {
+  title?: string;
+  pages: RelatedPage[];
+  onNavigate?: (id: string) => void;
+}
+
+export function RelatedPages({ title = '🔗 相关阅读', pages, onNavigate }: RelatedPagesProps) {
+  return (
+    <div className="mt-8 p-5 bg-[var(--bg-panel)] rounded-xl border border-[var(--border-subtle)]">
+      <h3 className="text-sm font-bold font-mono text-[var(--text-muted)] mb-4 flex items-center gap-2">
+        {title}
+      </h3>
+      <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-3">
+        {pages.map((page) => (
+          <button
+            key={page.id}
+            onClick={() => onNavigate?.(page.id)}
+            className="text-left p-3 bg-[var(--bg-card)] rounded-lg border border-[var(--border-subtle)] hover:border-[var(--terminal-green)] hover:bg-[var(--terminal-green)]/5 transition-all group"
+          >
+            <div className="font-mono text-sm text-[var(--text-primary)] group-hover:text-[var(--terminal-green)] flex items-center gap-2">
+              <span className="text-[var(--text-muted)] group-hover:text-[var(--terminal-green)]">→</span>
+              {page.label}
+            </div>
+            {page.description && (
+              <div className="text-xs text-[var(--text-muted)] mt-1">{page.description}</div>
+            )}
+          </button>
+        ))}
+      </div>
+    </div>
+  );
+}

src/contexts/NavigationContext.tsx

@@ -0,0 +1,25 @@
+import { createContext, useContext } from 'react';
+
+export interface NavigationContextValue {
+  navigate: (tabId: string, opts?: { replace?: boolean; preserveHash?: boolean }) => void;
+}
+
+export const NavigationContext = createContext<NavigationContextValue | null>(null);
+
+/**
+ * Hook to access the navigation function from any page component.
+ *
+ * @example
+ * ```tsx
+ * const { navigate } = useNavigation();
+ * // Navigate to another page
+ * navigate('token-accounting');
+ * ```
+ */
+export function useNavigation(): NavigationContextValue {
+  const ctx = useContext(NavigationContext);
+  if (!ctx) {
+    throw new Error('useNavigation must be used within a NavigationContext.Provider');
+  }
+  return ctx;
+}

src/pages/AuthenticationFlow.tsx

@@ -3,6 +3,7 @@ import { Layer } from '../components/Layer';
 import { HighlightBox } from '../components/HighlightBox';
 import { CodeBlock } from '../components/CodeBlock';
 import { MermaidDiagram } from '../components/MermaidDiagram';
+import { useNavigation } from '../contexts/NavigationContext';
 
 function CollapsibleSection({
   title,
@@ -35,6 +36,8 @@ function CollapsibleSection({
 }
 
 export function AuthenticationFlow() {
+  const { navigate } = useNavigation();
+
   return (
     <div>
       <h2 className="text-2xl text-cyan-400 mb-5">认证流程详解</h2>
@@ -635,9 +638,9 @@ private async acquireLock(lockPath: string): Promise<void> {
           <h4 className="text-cyan-400 font-semibold mb-2">相关页面</h4>
           <p className="text-sm text-gray-300">
             详细的 SharedTokenManager 架构和实现请参考：
-            <a href="#shared-token-manager" className="text-cyan-400 hover:underline ml-2">
+            <button onClick={() => navigate('shared-token-manager')} className="text-cyan-400 hover:underline ml-2 bg-transparent border-none cursor-pointer">
               → Token 共享机制
-            </a>
+            </button>
           </p>
         </div>
       </CollapsibleSection>
@@ -870,18 +873,18 @@ try {
       <div className="mt-8 p-4 bg-gray-800/50 rounded-lg">
         <h3 className="text-lg font-semibold text-cyan-400 mb-3">相关页面</h3>
         <div className="grid grid-cols-1 md:grid-cols-3 gap-4">
-          <a href="#shared-token-manager" className="block p-3 bg-gray-700/50 rounded hover:bg-gray-700 transition-colors">
+          <button onClick={() => navigate('shared-token-manager')} className="block p-3 bg-gray-700/50 rounded hover:bg-gray-700 transition-colors text-left border-none cursor-pointer">
             <div className="text-purple-400 font-semibold">Token 共享机制</div>
             <div className="text-sm text-gray-400">SharedTokenManager 完整架构</div>
-          </a>
-          <a href="#startup-chain" className="block p-3 bg-gray-700/50 rounded hover:bg-gray-700 transition-colors">
+          </button>
+          <button onClick={() => navigate('startup-chain')} className="block p-3 bg-gray-700/50 rounded hover:bg-gray-700 transition-colors text-left border-none cursor-pointer">
             <div className="text-blue-400 font-semibold">启动链路</div>
             <div className="text-sm text-gray-400">认证如何触发</div>
-          </a>
-          <a href="#config" className="block p-3 bg-gray-700/50 rounded hover:bg-gray-700 transition-colors">
+          </button>
+          <button onClick={() => navigate('config')} className="block p-3 bg-gray-700/50 rounded hover:bg-gray-700 transition-colors text-left border-none cursor-pointer">
             <div className="text-green-400 font-semibold">配置系统</div>
             <div className="text-sm text-gray-400">认证相关配置项</div>
-          </a>
+          </button>
         </div>
       </div>
     </div>

src/pages/CommandExecutionContext.tsx

@@ -6,9 +6,11 @@
 import { useState } from 'react';
 import { CodeBlock } from '../components/CodeBlock';
 import { MermaidDiagram } from '../components/MermaidDiagram';
+import { useNavigation } from '../contexts/NavigationContext';
 
 export function CommandExecutionContext() {
   const [activeTab, setActiveTab] = useState<'context' | 'loaders' | 'actions' | 'flow'>('context');
+  const { navigate } = useNavigation();
 
   return (
     <div className="max-w-4xl mx-auto">
@@ -933,49 +935,61 @@ export const chatCommand: SlashCommand = {
         <h2>🔗 相关文档</h2>
 
         <div style={{ display: 'grid', gridTemplateColumns: 'repeat(auto-fit, minmax(200px, 1fr))', gap: '1rem' }}>
-          <a href="#slash-cmd" className="card" style={{
+          <button onClick={() => navigate('slash-cmd')} className="card" style={{
             padding: '1rem',
             textDecoration: 'none',
             background: 'rgba(59, 130, 246, 0.1)',
             borderRadius: '8px',
-            transition: 'transform 0.2s'
+            transition: 'transform 0.2s',
+            border: 'none',
+            cursor: 'pointer',
+            textAlign: 'left'
           }}>
             <h4 style={{ color: 'var(--cyber-blue)', margin: '0 0 0.5rem 0' }}>💻 斜杠命令</h4>
             <p style={{ margin: 0, fontSize: '0.9rem' }}>命令系统概述</p>
-          </a>
+          </button>
 
-          <a href="#custom-cmd" className="card" style={{
+          <button onClick={() => navigate('custom-cmd')} className="card" style={{
             padding: '1rem',
             textDecoration: 'none',
             background: 'rgba(139, 92, 246, 0.1)',
             borderRadius: '8px',
-            transition: 'transform 0.2s'
+            transition: 'transform 0.2s',
+            border: 'none',
+            cursor: 'pointer',
+            textAlign: 'left'
           }}>
             <h4 style={{ color: 'var(--purple-accent)', margin: '0 0 0.5rem 0' }}>📝 自定义命令</h4>
             <p style={{ margin: 0, fontSize: '0.9rem' }}>TOML 文件格式详解</p>
-          </a>
+          </button>
 
-          <a href="#mcp" className="card" style={{
+          <button onClick={() => navigate('mcp')} className="card" style={{
             padding: '1rem',
             textDecoration: 'none',
             background: 'rgba(16, 185, 129, 0.1)',
             borderRadius: '8px',
-            transition: 'transform 0.2s'
+            transition: 'transform 0.2s',
+            border: 'none',
+            cursor: 'pointer',
+            textAlign: 'left'
           }}>
             <h4 style={{ color: 'var(--terminal-green)', margin: '0 0 0.5rem 0' }}>🌐 MCP 集成</h4>
             <p style={{ margin: 0, fontSize: '0.9rem' }}>MCP 提示加载机制</p>
-          </a>
+          </button>
 
-          <a href="#approval-mode" className="card" style={{
+          <button onClick={() => navigate('approval-mode')} className="card" style={{
             padding: '1rem',
             textDecoration: 'none',
             background: 'rgba(245, 158, 11, 0.1)',
             borderRadius: '8px',
-            transition: 'transform 0.2s'
+            transition: 'transform 0.2s',
+            border: 'none',
+            cursor: 'pointer',
+            textAlign: 'left'
           }}>
             <h4 style={{ color: 'var(--warning-color)', margin: '0 0 0.5rem 0' }}>🛡️ 审批模式</h4>
             <p style={{ margin: 0, fontSize: '0.9rem' }}>Shell 命令确认流程</p>
-          </a>
+          </button>
         </div>
       </section>
     </div>