@hutusi/amytis 1.16.0 → 1.17.0

package/src/components/ImmersiveSeriesSidebar.tsx

@@ -0,0 +1,143 @@
+'use client';
+
+import { useRef } from 'react';
+import { useSearchParams } from 'next/navigation';
+import Link from 'next/link';
+import type { PostData, CollectionContext, Heading } from '@/lib/markdown';
+import { useLanguage } from './LanguageProvider';
+import { useImmersiveReading } from './ImmersiveReadingProvider';
+import { useSidebarAutoScroll } from '@/hooks/useSidebarAutoScroll';
+import InlineBookToc from './InlineBookToc';
+import { getPostUrl, getPostUrlInCollection, getSeriesListUrl, getSeriesUrl } from '@/lib/urls';
+
+// Dedicated TOC sidebar for the immersive reader on a series post. Visually
+// mirrors BookSidebar's `mode="fill"` shape (clean numbered list, left-
+// border accent on the current item, inlined headings under the current
+// post, footer pointing at the listing page) rather than the page-mode
+// SeriesList card — see PR #95 review feedback.
+
+interface ImmersiveSeriesSidebarProps {
+  seriesSlug: string;
+  seriesTitle: string;
+  posts: PostData[];
+  /** When the post is in a collection, the sidebar can render in that
+   *  collection's scope by appending `?collection=<slug>` to the URL. Same
+   *  resolution logic as SeriesList. */
+  collectionContexts?: CollectionContext[];
+  currentSlug: string;
+  /** h2/h3 headings for the current post — rendered as an inline TOC under
+   *  the current post's row via the shared InlineBookToc component. */
+  headings?: Heading[];
+}
+
+export default function ImmersiveSeriesSidebar({
+  seriesSlug,
+  seriesTitle,
+  posts,
+  collectionContexts,
+  currentSlug,
+  headings = [],
+}: ImmersiveSeriesSidebarProps) {
+  const { t } = useLanguage();
+  const { enabled: immersiveEnabled } = useImmersiveReading();
+  const searchParams = useSearchParams();
+  const collectionParam = searchParams.get('collection');
+  const activeCollection = collectionParam
+    ? (collectionContexts ?? []).find(c => c.slug === collectionParam) ?? null
+    : null;
+
+  const effectiveSlug = activeCollection?.slug ?? seriesSlug;
+  const effectiveTitle = activeCollection?.title ?? seriesTitle;
+  const effectivePosts = activeCollection?.posts ?? posts;
+  const isCollectionContext = !!activeCollection;
+
+  // Collections mix posts from different layout segments (`/posts/[slug]` vs
+  // `/[series]/[slug]`). When clicking across that boundary, the
+  // ImmersiveReadingProvider remounts with `enabled=false` and the overlay
+  // closes. Appending `?immersive=1` lets the destination layout's
+  // ImmersiveReadingFlagHandler re-enter the reader and strip the flag.
+  const postHref = (post: PostData) => {
+    const base = activeCollection
+      ? getPostUrlInCollection(post, activeCollection.slug)
+      : getPostUrl(post);
+    if (!immersiveEnabled) return base;
+    const sep = base.includes('?') ? '&' : '?';
+    return `${base}${sep}immersive=1`;
+  };
+
+  const currentIndex = effectivePosts.findIndex(p => p.slug === currentSlug);
+  const currentItemRef = useRef<HTMLLIElement>(null);
+  const sidebarRef = useRef<HTMLElement>(null);
+  useSidebarAutoScroll(sidebarRef, currentItemRef, currentSlug);
+
+  if (effectivePosts.length === 0) return null;
+
+  return (
+    <aside
+      ref={sidebarRef}
+      className="block w-full h-full overflow-y-auto px-4 py-6 scrollbar-hide hover:scrollbar-thin"
+    >
+      {/* Header — series / collection label + post count + title link */}
+      <div className="mb-6 pb-4 border-b border-muted/10">
+        <div className="flex items-center justify-between mb-2">
+          <span className="text-[10px] font-sans font-bold uppercase tracking-widest text-accent">
+            {isCollectionContext ? t('collection') : t('series')}
+          </span>
+          <span className="text-xs font-mono text-muted whitespace-nowrap">
+            {currentIndex + 1}/{effectivePosts.length}
+          </span>
+        </div>
+        <Link href={getSeriesUrl(effectiveSlug)} className="group block no-underline">
+          <h3 className="font-serif font-bold text-heading text-lg leading-snug group-hover:text-accent transition-colors">
+            {effectiveTitle}
+          </h3>
+        </Link>
+      </div>
+
+      {/* Posts list — flat, current with left-border + accent (same treatment
+          as BookSidebar's chapter link). Past posts dimmed less than future
+          posts, also matching BookSidebar. */}
+      <nav aria-label={isCollectionContext ? t('collection') : t('series')}>
+        <ul className="space-y-1">
+          {effectivePosts.map((post, index) => {
+            const isCurrent = post.slug === currentSlug;
+            const isPast = index < currentIndex;
+            return (
+              <li key={post.slug} ref={isCurrent ? currentItemRef : undefined}>
+                <Link
+                  href={postHref(post)}
+                  className={`block py-2 px-3 rounded-lg text-sm no-underline transition-all duration-200 ${
+                    isCurrent
+                      ? 'bg-accent/10 text-accent font-semibold border-l-2 border-accent'
+                      : isPast
+                        ? 'text-foreground/70 hover:text-foreground hover:bg-muted/5'
+                        : 'text-muted hover:text-foreground hover:bg-muted/5'
+                  }`}
+                  aria-current={isCurrent ? 'page' : undefined}
+                >
+                  {post.title}
+                </Link>
+                {isCurrent && <InlineBookToc headings={headings} />}
+              </li>
+            );
+          })}
+        </ul>
+      </nav>
+
+      {/* Footer — points at the series listing (not back to the current
+          series detail, which the header already links to). Matches
+          BookSidebar's "All Books" footer pattern. */}
+      <div className="mt-6 pt-4 border-t border-muted/10">
+        <Link
+          href={getSeriesListUrl()}
+          className="text-xs font-sans text-muted hover:text-accent transition-colors no-underline flex items-center gap-1"
+        >
+          {t('all_series')}
+          <svg className="w-3 h-3" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={2}>
+            <path strokeLinecap="round" strokeLinejoin="round" d="M9 5l7 7-7 7" />
+          </svg>
+        </Link>
+      </div>
+    </aside>
+  );
+}

package/src/components/ImmersiveToggleButton.tsx

@@ -0,0 +1,45 @@
+'use client';
+
+import { useImmersiveReading } from '@/components/ImmersiveReadingProvider';
+import { useLanguage } from '@/components/LanguageProvider';
+
+export default function ImmersiveToggleButton() {
+  const { enabled, toggle } = useImmersiveReading();
+  const { t } = useLanguage();
+  // The button is the "enter" affordance; in immersive mode the top bar's
+  // exit (✕) is the only way out, so the inline button hides to avoid
+  // duplicating the exit and reading "Exit reading mode" next to it. Owning
+  // the visibility here means callers (PostLayout's article header, etc.)
+  // don't need to gate it with `{!enabled && ...}` separately.
+  if (enabled) return null;
+  const label = t('immersive_reading');
+
+  return (
+    <button
+      type="button"
+      onClick={toggle}
+      title={label}
+      aria-label={label}
+      className="inline-flex items-center gap-1.5 px-2 py-1 rounded-md text-xs font-sans text-muted hover:text-accent hover:bg-muted/10 transition-colors border border-transparent hover:border-muted/20 select-none"
+    >
+      <svg
+        width="14"
+        height="14"
+        viewBox="0 0 24 24"
+        fill="none"
+        stroke="currentColor"
+        strokeWidth="2"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+        aria-hidden="true"
+      >
+        <path d="M3 7V5a2 2 0 0 1 2-2h2" />
+        <path d="M17 3h2a2 2 0 0 1 2 2v2" />
+        <path d="M21 17v2a2 2 0 0 1-2 2h-2" />
+        <path d="M7 21H5a2 2 0 0 1-2-2v-2" />
+        <path d="M8 12h8" />
+      </svg>
+      <span className="hidden sm:inline">{label}</span>
+    </button>
+  );
+}

package/src/components/MarkdownRenderer.tsx

@@ -31,6 +31,22 @@ import { parseFenceMeta } from '@/lib/shiki';
 import { isExternalUrl } from '@/lib/urls';
 
 
+// Flatten an arbitrary React children tree to its text content. Used by the
+// raw-HTML <mermaid> handler below — react-markdown hands us the mermaid
+// source as a tree of text nodes (possibly nested through whitespace-only
+// wrappers) and the Mermaid component expects a single string.
+function flattenChildrenToText(node: React.ReactNode): string {
+  if (node == null || typeof node === 'boolean') return '';
+  if (typeof node === 'string') return node;
+  if (typeof node === 'number') return String(node);
+  if (Array.isArray(node)) return node.map(flattenChildrenToText).join('');
+  if (React.isValidElement(node)) {
+    const children = (node.props as { children?: React.ReactNode }).children;
+    return flattenChildrenToText(children);
+  }
+  return '';
+}
+
 interface MarkdownRendererProps {
   content: string;
   latex?: boolean;
@@ -280,6 +296,21 @@ export default function MarkdownRenderer({ content, latex = false, slug, slugReg
     globaltoc: ({ children }: { children?: React.ReactNode }) => <>{children}</>,
     homehero: () => null,
     chatdemo: () => null,
+    // <mermaid>...graph syntax...</mermaid> is the VuePress inline form. We
+    // already handle ```mermaid fenced blocks via the `code` renderer above;
+    // route the raw-HTML form to the same Mermaid component by flattening
+    // the children to a string.
+    mermaid: ({ children }: { children?: React.ReactNode }) => (
+      <Mermaid chart={flattenChildrenToText(children).trim()} />
+    ),
+    // <GitHubWrapper>...</GitHubWrapper> wraps GitHub project links / cards
+    // in the fenix VuePress book. Pass children through unchanged — they're
+    // usually a paragraph or an <a>/<img> the author wants to display.
+    githubwrapper: ({ children }: { children?: React.ReactNode }) => <>{children}</>,
+    // <words type='span' chapter='/' /> is a VuePress word-count widget that
+    // we can't reproduce without the upstream counter. Render nothing — the
+    // surrounding prose ("全文合计 X 字") degrades to "全文合计  字".
+    words: () => null,
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
   } as any;
 

package/src/components/Navbar.tsx

@@ -91,7 +91,9 @@ export default function Navbar({ seriesList = [], booksList = [] }: NavbarProps)
   }, [isMenuOpen]);
 
   return (
-    <nav className={`fixed top-0 left-0 w-full z-50 border-b transition-all duration-300 select-none ${
+    <nav
+      data-site-nav
+      className={`fixed top-0 left-0 w-full z-50 border-b transition-all duration-300 select-none ${
       isScrolled
         ? 'border-muted/10 bg-background/90 backdrop-blur-md shadow-sm'
         : 'border-transparent bg-transparent'

package/src/components/PostReadingShell.tsx

@@ -0,0 +1,68 @@
+'use client';
+
+import type { ReactNode } from 'react';
+import { useImmersiveReading } from '@/components/ImmersiveReadingProvider';
+import ImmersiveReader from '@/components/ImmersiveReader';
+import ImmersiveSeriesSidebar from '@/components/ImmersiveSeriesSidebar';
+import { getSeriesUrl } from '@/lib/urls';
+import type { CollectionContext, Heading, PostData } from '@/lib/markdown';
+
+interface PostReadingShellProps {
+  post: { slug: string; title: string; series?: string; headings?: Heading[] };
+  seriesSlug?: string;
+  seriesTitle?: string;
+  seriesPosts?: PostData[];
+  collectionContexts?: CollectionContext[];
+  /** Slim article subtree to render inside the overlay (header + body + nav).
+   *  Pre-built in PostLayout so the heavy MarkdownRenderer/RstRenderer is the
+   *  same ReactElement reference as in `children` — only one of the two ever
+   *  mounts, so the body renders exactly once. */
+  overlayArticle: ReactNode;
+  /** Full normal-mode layout subtree (sidebar + article + comments + nav +
+   *  related etc.). Rendered when immersive is off OR the post isn't in a
+   *  series. */
+  children: ReactNode;
+}
+
+/**
+ * Post-side analog of BookReadingShell. Branches on the immersive `enabled`
+ * flag AND whether the post belongs to a series — without a series there's no
+ * meaningful TOC for the overlay sidebar, so the toggle is a no-op and we
+ * just render the normal layout.
+ */
+export default function PostReadingShell({
+  post,
+  seriesSlug,
+  seriesTitle,
+  seriesPosts,
+  collectionContexts,
+  overlayArticle,
+  children,
+}: PostReadingShellProps) {
+  const { enabled } = useImmersiveReading();
+  const inSeries = !!(seriesSlug && seriesPosts && seriesPosts.length > 0);
+
+  if (!enabled || !inSeries) {
+    return <>{children}</>;
+  }
+
+  return (
+    <ImmersiveReader
+      rootHref={getSeriesUrl(seriesSlug)}
+      rootTitle={seriesTitle ?? seriesSlug}
+      currentTitle={post.title}
+      sidebar={
+        <ImmersiveSeriesSidebar
+          seriesSlug={seriesSlug}
+          seriesTitle={seriesTitle ?? seriesSlug}
+          posts={seriesPosts}
+          collectionContexts={collectionContexts}
+          currentSlug={post.slug}
+          headings={post.headings}
+        />
+      }
+    >
+      {overlayArticle}
+    </ImmersiveReader>
+  );
+}

package/src/components/ReadingProgressBar.tsx

@@ -12,7 +12,7 @@ export default function ReadingProgressBar() {
   if (progress <= 0) return null;
 
   return (
-    <div className="fixed top-16 left-0 w-full h-0.5 z-50 bg-muted/10">
+    <div data-reading-progress className="fixed top-16 left-0 w-full h-0.5 z-50 bg-muted/10">
       <div
         className="h-full bg-accent/70 transition-[width] duration-150 ease-out"
         style={{ width: `${progress}%` }}

package/src/components/SelectedBooksSection.tsx

@@ -1,11 +1,12 @@
 'use client';
 
-import { useState, useCallback } from 'react';
+import { useState, useEffect, useCallback } from 'react';
 import Link from 'next/link';
 import CoverImage from './CoverImage';
 import HorizontalScroll from './HorizontalScroll';
 import { useLanguage } from './LanguageProvider';
-import { shuffle, shuffleSeeded } from '@/lib/shuffle';
+import { shuffle } from '@/lib/shuffle';
+import { byDateAsc, byDateDesc } from '@/lib/sort';
 import { getBooksListUrl, getBookUrl, getBookChapterUrl } from '@/lib/urls';
 
 export interface BookItem {
@@ -16,19 +17,37 @@ export interface BookItem {
   authors: string[];
   chapterCount: number;
   firstChapter?: string;
+  date: string;
 }
 
+type BookOrder = 'shuffle' | 'date-desc' | 'date-asc';
+
 interface SelectedBooksSectionProps {
   books: BookItem[];
   maxItems?: number;
+  order?: BookOrder;
+}
+
+function canonicalOrder(books: BookItem[], order: BookOrder): BookItem[] {
+  if (order === 'date-desc') return [...books].sort(byDateDesc);
+  if (order === 'date-asc')  return [...books].sort(byDateAsc);
+  // For 'shuffle': SSR-stable canonical order (input is already date-desc from getAllBooks).
+  // The post-mount useEffect swaps to a random permutation on the client.
+  return books;
 }
 
-export default function SelectedBooksSection({ books, maxItems = 4 }: SelectedBooksSectionProps) {
+export default function SelectedBooksSection({ books, maxItems = 4, order = 'shuffle' }: SelectedBooksSectionProps) {
   const { t } = useLanguage();
-  const [displayed, setDisplayed] = useState(() => {
-    const dailySeed = Math.floor(Date.now() / 86400000);
-    return shuffleSeeded(books, dailySeed).slice(0, maxItems);
-  });
+  const [displayed, setDisplayed] = useState(() => canonicalOrder(books, order).slice(0, maxItems));
+
+  // Shuffle on mount so every reload re-rolls. SSR's canonical render is stable; the
+  // post-hydration swap is the intentional client-only behaviour, not a sync issue.
+  useEffect(() => {
+    if (order === 'shuffle') {
+      // eslint-disable-next-line react-hooks/set-state-in-effect
+      setDisplayed(shuffle(books).slice(0, maxItems));
+    }
+  }, [books, maxItems, order]);
 
   const handleShuffle = useCallback(() => {
     setDisplayed(shuffle(books).slice(0, maxItems));
@@ -41,7 +60,7 @@ export default function SelectedBooksSection({ books, maxItems = 4 }: SelectedBo
       <div className="flex items-center justify-between mb-8">
         <h2 className="text-2xl sm:text-3xl font-serif font-bold text-heading">{t('selected_books')}</h2>
         <div className="flex items-center gap-4">
-          {books.length > maxItems && (
+          {order === 'shuffle' && books.length > maxItems && (
             <button
               onClick={handleShuffle}
               className="rounded-sm text-sm text-muted transition-colors hover:text-accent focus:outline-none focus-visible:ring-2 focus-visible:ring-accent/50 focus-visible:ring-offset-2"

package/src/hooks/useActiveHeading.ts

@@ -2,11 +2,12 @@
 
 import { useState, useEffect } from 'react';
 import type { Heading } from '@/lib/markdown';
-import { useScrollY } from './useScrollY';
+import { getScrollableAncestor } from '@/lib/scroll-utils';
+
+const ACTIVATION_LINE_PX = 100;
 
 export function useActiveHeading(headings: Heading[], enabled = true): string {
   const [activeId, setActiveId] = useState('');
-  const scrollY = useScrollY();
 
   useEffect(() => {
     if (!enabled || headings.length === 0) return;
@@ -14,19 +15,40 @@ export function useActiveHeading(headings: Heading[], enabled = true): string {
     const elements = headings
       .map(h => document.getElementById(h.id))
       .filter(Boolean) as HTMLElement[];
-
     if (elements.length === 0) return;
 
-    const scrollPosition = scrollY + 100;
-    let current = elements[0];
-    for (const el of elements) {
-      if (el.offsetTop <= scrollPosition) current = el;
-      else break;
-    }
-
-    const rafId = requestAnimationFrame(() => { if (current) setActiveId(current.id); });
-    return () => cancelAnimationFrame(rafId);
-  }, [scrollY, headings, enabled]);
+    // In immersive reading mode the chapter scrolls inside the overlay's
+    // <main>, not the window, so subscribe to whichever ancestor is doing
+    // the scrolling. `getScrollableAncestor` returns null for normal pages.
+    const container = getScrollableAncestor(elements[0]);
+    const target: HTMLElement | Window = container ?? window;
+
+    let rafId = 0;
+    const compute = () => {
+      const containerTop = container
+        ? container.getBoundingClientRect().top
+        : 0;
+      let current = elements[0];
+      for (const el of elements) {
+        const top = el.getBoundingClientRect().top - containerTop;
+        if (top <= ACTIVATION_LINE_PX) current = el;
+        else break;
+      }
+      setActiveId(current.id);
+    };
+
+    const onScroll = () => {
+      cancelAnimationFrame(rafId);
+      rafId = requestAnimationFrame(compute);
+    };
+
+    compute();
+    target.addEventListener('scroll', onScroll, { passive: true });
+    return () => {
+      cancelAnimationFrame(rafId);
+      target.removeEventListener('scroll', onScroll);
+    };
+  }, [enabled, headings]);
 
   return activeId;
 }

package/src/hooks/useSidebarAutoScroll.ts

@@ -1,18 +1,42 @@
 'use client';
 
-import { useEffect, type RefObject } from 'react';
+import { useEffect, useRef, type RefObject } from 'react';
 
+/**
+ * Scrolls the current sidebar item into view when `dep` changes.
+ *
+ * - **First run** (sidebar just mounted — e.g. the reader landed on a page
+ *   mid-TOC): centres the current item so there's context above and below.
+ * - **Subsequent runs** (the reader clicked another sidebar link to
+ *   navigate): only scrolls if the new current item is out of view, and
+ *   only enough to bring it on-screen. Crucially, if the target was
+ *   already visible, the sidebar's scroll position does **not** change —
+ *   clicking a chapter right in front of you no longer makes the sidebar
+ *   jump.
+ *
+ * The previous implementation always hard-centred via `scrollTop = ...`
+ * regardless of visibility, which on long book TOCs visibly snapped the
+ * sidebar back toward the top whenever the new current chapter was in
+ * the upper half. `scrollIntoView({ block: 'nearest' })` handles the
+ * "skip if already visible" case natively. The `sidebarRef` first
+ * parameter is kept for API stability (all callers still pass it); the
+ * new implementation doesn't need it because `scrollIntoView` walks up
+ * to the nearest scrollable ancestor on its own.
+ */
 export function useSidebarAutoScroll(
-  sidebarRef: RefObject<HTMLElement | null>,
+  _sidebarRef: RefObject<HTMLElement | null>,
   itemRef: RefObject<HTMLElement | null>,
   dep: unknown,
 ): void {
+  const hasRunRef = useRef(false);
   useEffect(() => {
-    if (itemRef.current && sidebarRef.current) {
-      const item = itemRef.current;
-      const sidebar = sidebarRef.current;
-      sidebar.scrollTop = item.offsetTop - sidebar.clientHeight / 2 + item.offsetHeight / 2;
-    }
+    const item = itemRef.current;
+    if (!item) return;
+    item.scrollIntoView({
+      block: hasRunRef.current ? 'nearest' : 'center',
+      inline: 'nearest',
+    });
+    hasRunRef.current = true;
   // refs are stable; only re-run when dep changes
   // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [dep]);

package/src/i18n/translations.ts

@@ -145,6 +145,27 @@ export const translations = {
     archive_description: "A complete chronological archive of all articles.",
     tags_description: "Explore topics spanning all articles and flow notes.",
     posts_description: "Browse all articles.",
+    immersive_reading: "Immersive reading",
+    exit_reading_mode: "Exit reading mode",
+    reading_preferences: "Reading preferences",
+    font_size: "Font size",
+    reading_theme: "Theme",
+    column_width: "Width",
+    theme_auto: "Auto",
+    theme_light: "Light",
+    theme_sepia: "Sepia",
+    theme_dark: "Dark",
+    size_small: "S",
+    size_medium: "M",
+    size_large: "L",
+    size_xl: "XL",
+    width_narrow: "Narrow",
+    width_medium: "Medium",
+    width_wide: "Wide",
+    width_full: "Full",
+    collapse_sidebar: "Collapse sidebar",
+    expand_sidebar: "Expand sidebar",
+    reset_to_defaults: "Reset to defaults",
   },
   zh: {
     home: "首页",
@@ -292,6 +313,27 @@ export const translations = {
     archive_description: "全部文章的时间轴归档。",
     tags_description: "浏览全部文章与随笔的主题标签。",
     posts_description: "浏览全部文章。",
+    immersive_reading: "沉浸式阅读",
+    exit_reading_mode: "退出阅读模式",
+    reading_preferences: "阅读设置",
+    font_size: "字号",
+    reading_theme: "主题",
+    column_width: "宽度",
+    theme_auto: "自动",
+    theme_light: "浅色",
+    theme_sepia: "护眼",
+    theme_dark: "深色",
+    size_small: "小",
+    size_medium: "中",
+    size_large: "大",
+    size_xl: "特大",
+    width_narrow: "窄",
+    width_medium: "中",
+    width_wide: "宽",
+    width_full: "全宽",
+    collapse_sidebar: "收起目录",
+    expand_sidebar: "展开目录",
+    reset_to_defaults: "恢复默认",
   },
 };