hd-garden 0.9.0 → 0.9.2

package/app/bookshelf/load.mjs

@@ -0,0 +1,96 @@
+import fs from "node:fs";
+import path from "node:path";
+import matter from "gray-matter";
+import { parse as parseYaml } from "yaml";
+import { gardenSiteRoot } from "../../scripts/garden-paths.mjs";
+import { bookshelfMountFromFile, normalizeBookshelfPostPath } from "../components/bookshelf/catalog.mjs";
+import { BookshelfConfigError, parseBookshelfConfig } from "../components/bookshelf/schema.mjs";
+
+export function bookshelfConfigPath(root = gardenSiteRoot()) {
+  return path.join(root, "content", "bookshelf.yaml");
+}
+
+/**
+ * The site shelf, or null when `content/bookshelf.yaml` is absent.
+ * Absent means the package demo (click-test only). A file here is the live shelf:
+ * each book's `post` is read from `content/posts` and turned into note HTML.
+ * `preparedPosts`, when passed, are the sync pipeline's posts (rewritten asset
+ * URLs). Otherwise the markdown files are read directly.
+ * Throws `BookshelfConfigError` when the file, a cover, or a post path is broken.
+ */
+export function loadBookshelf(root = gardenSiteRoot(), preparedPosts) {
+  const file = bookshelfConfigPath(root);
+  if (!fs.existsSync(file)) return null;
+  let parsed;
+  try {
+    parsed = parseYaml(fs.readFileSync(file, "utf8"));
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : "无法解析";
+    throw new BookshelfConfigError("invalid-root", `content/bookshelf.yaml 无法解析：${detail}`);
+  }
+  const config = parseBookshelfConfig(parsed);
+  const sources = preparedPosts
+    ? preparedPosts.map((post) => ({
+      path: post.path,
+      title: post.title,
+      description: post.description,
+      cover: post.cover,
+      content: post.content,
+    }))
+    : readReferencedPosts(root, config);
+  return bookshelfMountFromFile(config, sources);
+}
+
+function readReferencedPosts(root, config) {
+  const seen = new Set();
+  const posts = [];
+  for (const shelf of config.shelves) {
+    for (const book of shelf.books) {
+      if (!book.post) continue;
+      const relative = normalizeBookshelfPostPath(book.post);
+      if (seen.has(relative)) continue;
+      seen.add(relative);
+      posts.push(readPost(root, relative));
+    }
+  }
+  return posts;
+}
+
+function readPost(root, postPath) {
+  const relative = normalizeBookshelfPostPath(postPath);
+  const postsRoot = path.resolve(root, "content", "posts");
+  const file = `${path.resolve(postsRoot, ...relative.split("/"))}.md`;
+  if (!file.startsWith(`${postsRoot}${path.sep}`)) {
+    throw new BookshelfConfigError("post", `post「${postPath}」必须是 content/posts 下的路径，不带 .md。`);
+  }
+  if (!fs.existsSync(file)) {
+    throw new BookshelfConfigError("post", `content/bookshelf.yaml 引用的博文 ${relative} 不存在。`);
+  }
+  let parsed;
+  try {
+    parsed = matter(fs.readFileSync(file, "utf8"), {
+      engines: {
+        yaml: {
+          parse: (input) => parseYaml(input) ?? {},
+        },
+      },
+    });
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : "无法解析";
+    throw new BookshelfConfigError("post", `博文 ${relative} 无法解析：${detail}`);
+  }
+  const data = parsed.data && typeof parsed.data === "object" ? parsed.data : {};
+  return {
+    path: relative,
+    title: optionalString(data.title),
+    description: optionalString(data.description),
+    cover: optionalString(data.cover),
+    content: parsed.content,
+  };
+}
+
+function optionalString(value) {
+  if (typeof value !== "string") return undefined;
+  const trimmed = value.trim();
+  return trimmed ? trimmed : undefined;
+}

package/app/bookshelf/load.ts

@@ -1,23 +1,16 @@
-import fs from "node:fs";
-import path from "node:path";
-import { parse as parseYaml } from "yaml";
-import { gardenSiteRoot } from "../../scripts/garden-paths.mjs";
-import { BookshelfConfigError, parseBookshelfConfig, type BookshelfFile } from "../components/bookshelf/schema";
+import type { BookshelfMount } from "../components/bookshelf/catalog";
+import { bookshelfConfigPath as configPath, loadBookshelf as readShelf } from "./load.mjs";
 
-export function bookshelfConfigPath(root = gardenSiteRoot()) {
-  return path.join(root, "content", "bookshelf.yaml");
+export type { BookshelfMount };
+
+export function bookshelfConfigPath(root?: string) {
+  return configPath(root) as string;
 }
 
-/** Site shelf, or null when the site has no `content/bookshelf.yaml`. */
-export function loadBookshelf(): BookshelfFile | null {
-  const file = bookshelfConfigPath();
-  if (!fs.existsSync(file)) return null;
-  let parsed: unknown;
-  try {
-    parsed = parseYaml(fs.readFileSync(file, "utf8"));
-  } catch (error) {
-    const detail = error instanceof Error ? error.message : "无法解析";
-    throw new BookshelfConfigError("invalid-root", `content/bookshelf.yaml 无法解析：${detail}`);
-  }
-  return parseBookshelfConfig(parsed);
+/**
+ * The site shelf, or null when `content/bookshelf.yaml` is absent.
+ * Absent means the package demo. See `load.mjs` for the file contract.
+ */
+export function loadBookshelf(root?: string): BookshelfMount | null {
+  return readShelf(root) as BookshelfMount | null;
 }

package/app/bookshelf/page.tsx

@@ -1,19 +1,52 @@
 import type { Metadata } from "next";
+import { bookshelf } from "@garden/bookshelf";
 import { Bookshelf } from "../components/bookshelf";
 import { siteLang } from "../lib/i18n";
-
-const preview = siteLang === "zh";
-
-export const metadata: Metadata = preview
-  ? { title: { absolute: "花园 · 读书笔记" }, robots: { index: false, follow: false } }
-  : { title: "Bookshelf", robots: { index: false, follow: false } };
+import { pageAlternates } from "../lib/page-alternates";
+import { siteConfig } from "../site.config";
 
 /**
- * Click-test route for the approved shelf.
- * States: ?mode=covers (A), default spines (B), hover one spine (C). ?debug=1 shows the demo's mode buttons.
- * English sites skip the Chinese demo markup so a locale=en build stays free of CJK.
+ * `/bookshelf` contract:
+ * - `content/bookshelf.yaml` present → that shelf, with each `post` rendered
+ *   into `notes`, inside the site header. Indexed like the other pages.
+ * - file absent → package demo (Chinese click-test only, noindex, no site chrome).
+ *   English builds skip the demo so a locale=en site stays free of that markup.
  */
+export async function generateMetadata(): Promise<Metadata> {
+  const shelf = bookshelf;
+  if (shelf) {
+    return {
+      title: shelf.title,
+      description: shelf.description,
+      alternates: pageAlternates("/bookshelf"),
+    };
+  }
+  if (siteLang === "zh") {
+    return { title: { absolute: "花园 · 读书笔记" }, robots: { index: false, follow: false } };
+  }
+  return { title: "Bookshelf", robots: { index: false, follow: false } };
+}
+
 export default function BookshelfPage() {
-  if (!preview) return null;
+  const shelf = bookshelf;
+  if (shelf) {
+    return (
+      <main className="sh-main bookshelf-page" id="content">
+        <header className="sh-head">
+          {shelf.eyebrow ? <p className="sh-kicker">{shelf.eyebrow}</p> : null}
+          <h1 id="sh-title">{shelf.title}</h1>
+          {shelf.description ? <p className="sh-deck">{shelf.description}</p> : null}
+        </header>
+        <Bookshelf
+          embedded
+          catalog={shelf.catalog}
+          notes={shelf.notes}
+          title={shelf.title}
+          eyebrow={shelf.eyebrow ?? siteConfig.name}
+        />
+      </main>
+    );
+  }
+  if (siteLang !== "zh") return null;
   return <Bookshelf />;
 }

package/app/components/SiteChrome.tsx

@@ -5,7 +5,14 @@ import { inAppPath, isHandbookPath, routeLang, ui } from "../lib/i18n";
 import { SiteFooter } from "./SiteFooter";
 import { SiteHeader } from "./SiteHeader";
 
-export function SiteChrome({ children }: { children: React.ReactNode }) {
+export function SiteChrome({
+  children,
+  bookshelfSite = false,
+}: {
+  children: React.ReactNode;
+  /** True when the site has content/bookshelf.yaml. The package demo stays chrome-less. */
+  bookshelfSite?: boolean;
+}) {
   const pathname = usePathname();
   const lang = routeLang(pathname);
   // The skip link follows the route language too (/garden/en/ is English).
@@ -14,18 +21,19 @@ export function SiteChrome({ children }: { children: React.ReactNode }) {
       {ui(lang).skipToContent}
     </a>
   );
-  // The shelf preview is the approved demo viewport, not a page inside the site header.
-  // Static export serves /bookshelf/ ; an exact "/bookshelf" check leaves the chrome on.
+  // The package demo (no content/bookshelf.yaml) is the approved chrome-less viewport.
+  // A site shelf is a normal page, so it keeps the header and footer.
+  // Static export serves /bookshelf/ ; an exact "/bookshelf" check would miss it.
   const path = inAppPath(pathname);
-  const shelfPreview = path === "/bookshelf" || path.startsWith("/bookshelf/");
-  if (path.startsWith("/admin") || shelfPreview) {
+  const shelfDemo = !bookshelfSite && (path === "/bookshelf" || path.startsWith("/bookshelf/"));
+  if (path.startsWith("/admin") || shelfDemo) {
     return <>{skip}{children}</>;
   }
 
   return (
     <>
       {skip}
-      <SiteHeader />
+      <SiteHeader shelf={bookshelfSite} />
       <div id="main-content">{children}</div>
       <SiteFooter docs={isHandbookPath(pathname)} lang={lang} />
     </>

package/app/components/SiteHeader.tsx

@@ -16,7 +16,7 @@ import { brand, searchFull, searchIndexUrl } from "@garden/site-config";
 import { createSearch } from "../../ui/garden/search-match.mjs";
 import { cropMatchedText, highlightParts } from "../../ui/garden/search-preview.mjs";
 import { resolveDark, themeSwitchProps } from "../../ui/garden/theme.mjs";
-import { SITE_NAV, isCurrentNav } from "../../ui/garden/site-nav.mjs";
+import { siteNav, isCurrentNav } from "../../ui/garden/site-nav.mjs";
 import { isHandbookPath, routeLang, ui } from "../lib/i18n";
 import { HandbookLangSwitch } from "./HandbookLangSwitch";
 import { createIdbStore, loadFullIndex, saveDataOn, whenIdleAfterLoad } from "../../ui/garden/search-full.mjs";
@@ -89,7 +89,6 @@ function loadSearchEngine() {
   return engineLoad;
 }
 
-const nav = SITE_NAV.map((item) => ({ ...item, key: item.href, href: siteHref(item.href) }));
 
 function rangesFor(
   matches: readonly SearchMatch[] | undefined,
@@ -140,7 +139,8 @@ function searchPreview(
   return { prefix: "", text: item.description, suffix: "", ranges: [] };
 }
 
-export function SiteHeader() {
+export function SiteHeader({ shelf = false }: { shelf?: boolean }) {
+  const nav = siteNav({ shelf }).map((item) => ({ ...item, key: item.href, href: siteHref(item.href) }));
   const pathname = usePathname() || "/";
   const t = ui(routeLang(pathname));
   const [menuOpen, setMenuOpen] = useState(false);

package/app/components/bookshelf/Bookshelf.tsx

@@ -1,16 +1,53 @@
 "use client";
 
 import { useLayoutEffect, useRef } from "react";
+import { siteHref } from "../../lib/site-href";
 import { mountBookshelf } from "./engine";
-import type { BookshelfProps } from "./types";
+import type { BookshelfProps, BookshelfShelf } from "./types";
 import "./bookshelf.css";
 
-const SHELL = `
+const SHELF_SCROLL_KEY = "garden-bookshelf-scroll";
+
+function withNoteLinks(catalog: BookshelfShelf[] | undefined) {
+  if (!catalog) return catalog;
+  return catalog.map((row) => ({
+    ...row,
+    books: row.books.map((book) =>
+      book.post ? { ...book, href: siteHref(`/blog/${book.post}`) } : book,
+    ),
+  }));
+}
+
+function readSavedScroll() {
+  try {
+    const raw = sessionStorage.getItem(SHELF_SCROLL_KEY);
+    if (raw == null) return null;
+    sessionStorage.removeItem(SHELF_SCROLL_KEY);
+    const y = Number(raw);
+    return Number.isFinite(y) ? y : null;
+  } catch {
+    return null;
+  }
+}
+
+const DEMO_BRAND = "花园 · 读书笔记";
+const DEMO_TITLE = "读书笔记";
+
+function escapeHtml(value: string) {
+  return value
+    .replaceAll("&", "&")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;");
+}
+
+function shelfShell(brand: string, title: string) {
+  return `
     <div class="shelf-view" id="shelfView">
       <div class="page">
         <header class="top">
-          <div class="brand">花园 · 读书笔记</div>
-          <h1>读书笔记</h1>
+          <div class="brand">${escapeHtml(brand)}</div>
+          <h1>${escapeHtml(title)}</h1>
           <p class="lede is-debug" id="lede" hidden>调试说明：页级疏密；悬停/点按展一本；再点进笔记。</p>
           <div class="qa-bar is-debug" id="qaBar" role="group" aria-label="演示控制" hidden>
             <span class="qa-label">页级态</span>
@@ -37,6 +74,7 @@ const SHELL = `
             <p class="note-cat" id="noteCat"></p>
             <h1 id="noteTitle"></h1>
             <p class="note-author" id="noteAuthor"></p>
+            <a class="note-read" id="noteRead" hidden>阅读全文</a>
           </div>
         </div>
         <div class="note-body" id="noteBody"></div>
@@ -49,14 +87,31 @@ const SHELL = `
     </div>
     <div class="stage" id="stage" aria-hidden="true"></div>
 `;
+}
 
-/** Approved bookshelf. Pass `catalog` and `notes` to mount another shelf on the same motion. */
-export function Bookshelf({ catalog, notes }: BookshelfProps) {
+/** Approved bookshelf. Pass `catalog` and `notes` for a site shelf; omit them for the package demo. */
+export function Bookshelf({ catalog, notes, title, eyebrow, embedded = false }: BookshelfProps) {
   const ref = useRef<HTMLDivElement>(null);
   useLayoutEffect(() => {
     const root = ref.current;
     if (!root) return;
-    return mountBookshelf(root, { catalog, notes });
-  }, [catalog, notes]);
-  return <div className="bookshelf-demo" ref={ref} dangerouslySetInnerHTML={{ __html: SHELL }} />;
+    const saved = embedded ? readSavedScroll() : null;
+    const applyScroll = () => {
+      if (saved != null) window.scrollTo(0, saved);
+    };
+    applyScroll();
+    const unmount = mountBookshelf(root, { catalog: withNoteLinks(catalog), notes });
+    const frame = window.requestAnimationFrame(applyScroll);
+    return () => {
+      window.cancelAnimationFrame(frame);
+      unmount?.();
+    };
+  }, [catalog, notes, title, eyebrow, embedded]);
+  return (
+    <div
+      className={embedded ? "bookshelf-demo is-site" : "bookshelf-demo"}
+      ref={ref}
+      dangerouslySetInnerHTML={{ __html: shelfShell(eyebrow || DEMO_BRAND, title || DEMO_TITLE) }}
+    />
+  );
 }