hd-garden 0.6.1 → 0.7.0

package/app/admin/preview/[...path]/page.tsx

@@ -88,7 +88,7 @@ export default async function DraftPreviewPage({ params }: { params: Promise<{ p
         <h1 className="ui-admin-preview-title">{typeof data.title === "string" ? data.title : post}</h1>
         {typeof data.description === "string" ? <p className="ui-studio-meta">{data.description}</p> : null}
         <article className="article-body">
-          <MarkdownArticle content={proxyAssets(content, post)} />
+          <MarkdownArticle content={proxyAssets(content, post)} numbering={data.numbering === false ? false : undefined} />
         </article>
       </section>
     </AdminUiShell>

package/app/blog/[...path]/page.tsx

@@ -77,7 +77,7 @@ export default async function PostPage({
     if (isStaticPlaceholder(path)) return null;
     notFound();
   }
-  const headings = extractHeadings(post.content);
+  const headings = extractHeadings(post.content, { numbering: post.numbering });
   const baseUrl = await getSiteUrl();
   const pathname = postHref(post);
   const canonicalUrl = absoluteUrl(pathname, baseUrl);
@@ -125,7 +125,7 @@ export default async function PostPage({
             <ArticleMeasure />
             <div className="e-content">
               {post.description ? <p className="lead quote-plain p-summary">{post.description}</p> : null}
-              <MarkdownArticle content={post.content} />
+              <MarkdownArticle content={post.content} numbering={post.numbering} />
             </div>
             <ArticleReferences references={post.references} />
             <Webmentions

package/app/columns/[column]/[...path]/page.tsx

@@ -89,7 +89,7 @@ export default async function ColumnEntryPage({
   const listed = [...series].sort((left, right) => Date.parse(right.date) - Date.parse(left.date));
   const currentIndex = series.findIndex((item) => item.path === entry.path);
   const next = series[currentIndex + 1];
-  const headings = extractHeadings(entry.content);
+  const headings = extractHeadings(entry.content, { numbering: entry.numbering });
   const baseUrl = await getSiteUrl();
   const pathname = columnHref(entry);
   const canonicalUrl = absoluteUrl(pathname, baseUrl);
@@ -147,7 +147,7 @@ export default async function ColumnEntryPage({
         <ArticleMeasure />
         <div className="e-content">
           {entry.description ? <p className="lead p-summary">{entry.description}</p> : null}
-          <MarkdownArticle content={entry.content} />
+          <MarkdownArticle content={entry.content} numbering={entry.numbering} />
         </div>
         <ArticleReferences references={entry.references} />
         {next && (

package/app/components/ArticleMeasure.tsx

@@ -45,7 +45,14 @@ export function ArticleMeasure() {
       return width;
     };
 
+    const docPage = article.closest<HTMLElement>(".garden-doc-page");
+
     const placeToc = () => {
+      if (docPage) {
+        root.removeAttribute("data-toc-yield");
+        root.removeAttribute("data-toc-hide");
+        return;
+      }
       if (!toc) {
         root.removeAttribute("data-toc-yield");
         return;
@@ -74,10 +81,38 @@ export function ArticleMeasure() {
       }
     };
 
+    const clampMargin = (margin: { left: number; right: number }, maxRoom: number | null) => {
+      if (maxRoom === null) return margin;
+      const side = Math.max(0, Math.min(margin.left, maxRoom));
+      return { left: side, right: side };
+    };
+
     const measure = (refresh: boolean) => {
       // Measure the text column, not the whole article grid (which includes the TOC rail).
       const articleBox = (article.querySelector(".markdown-body") ?? article).getBoundingClientRect();
       const viewport = root.clientWidth;
+      let docMaxRoom: number | null = null;
+      if (docPage) {
+        const sidebar = docPage.querySelector<HTMLElement>(".gdoc-sidebar");
+        let leftLimit = 24;
+        if (sidebar && getComputedStyle(sidebar).position === "sticky") {
+          const sbBox = sidebar.getBoundingClientRect();
+          if (sbBox.width > 0 && sbBox.right <= articleBox.left + 1) {
+            leftLimit = sbBox.right + 16;
+          }
+        }
+        let rightLimit = viewport - 24;
+        if (toc && getComputedStyle(toc).display !== "none") {
+          const tocBox = toc.getBoundingClientRect();
+          if (tocBox.width > 0 && tocBox.left >= articleBox.right - 1) {
+            rightLimit = tocBox.left - translatedX(toc) - 16;
+          }
+        }
+        docMaxRoom = Math.max(
+          0,
+          Math.floor(Math.min(articleBox.left - leftLimit, rightLimit - articleBox.right)),
+        );
+      }
       const widen = (element: HTMLElement, margin: { left: number; right: number }) => {
         if (margin.left <= 0) return;
         element.style.setProperty("--wl", `${margin.left}px`);
@@ -89,13 +124,13 @@ export function ArticleMeasure() {
         const width = tableWidth(wrap, refresh);
         resetWide(wrap);
         if (!width) return;
-        widen(wrap, tableBreakout({
+        widen(wrap, clampMargin(tableBreakout({
           viewport,
           articleLeft: articleBox.left,
           articleRight: articleBox.right,
           tableClient: wrap.clientWidth,
           tableScroll: width,
-        }));
+        }), docMaxRoom));
       });
       // Images: as wide as they display (2x screenshots at half their pixels), up to 1040px in total.
       article.querySelectorAll<HTMLElement>(".fig").forEach((figure) => {
@@ -115,7 +150,7 @@ export function ArticleMeasure() {
         if (!pixels) return;
         // width="" written by the build is the pixel size, not an author's choice.
         const attrWidth = known ? Number(image.dataset.aw) || 0 : Number(image.getAttribute("width")) || 0;
-        const breakout = figureBreakout({
+        const breakout = clampMargin(figureBreakout({
           viewport,
           articleLeft: articleBox.left,
           articleRight: articleBox.right,
@@ -123,7 +158,7 @@ export function ArticleMeasure() {
           imageClient: image.clientWidth,
           naturalWidth: pixels,
           attrWidth,
-        });
+        }), docMaxRoom);
         widen(figure, breakout);
         // Only a widened image, or one with a width attribute, gets an inline width.
         const width = figureImageWidth({ naturalWidth: pixels, attrWidth, widened: breakout.left > 0 });

package/app/components/GardenDocsNav.tsx

@@ -0,0 +1,184 @@
+"use client";
+
+import { useCallback, useEffect, useId, useRef, useState } from "react";
+import Link from "next/link";
+import { BookOpenText, CaretRight, List, X } from "@phosphor-icons/react";
+import {
+  COMPONENT_BADGE,
+  groupHandbookDocs,
+  NAV_SHORT_TITLE,
+  type GardenDocNavItem,
+} from "../lib/garden-docs-meta";
+import { siteHref } from "../lib/site-href";
+
+export function GardenDocsNav({
+  docs,
+  currentPath = "",
+}: {
+  docs: GardenDocNavItem[];
+  currentPath?: string;
+}) {
+  const groups = groupHandbookDocs(docs);
+  const currentDoc = docs.find((doc) => doc.path === currentPath);
+  const currentSection = groups.find((group) =>
+    group.items.some((item) => item.path === currentPath),
+  );
+  const [mobileOpen, setMobileOpen] = useState(false);
+  const drawerId = useId();
+  const triggerRef = useRef<HTMLButtonElement>(null);
+  const closeRef = useRef<HTMLButtonElement>(null);
+  const restoreFocusRef = useRef(false);
+
+  const closeMobile = useCallback((restoreFocus = false) => {
+    restoreFocusRef.current = restoreFocus;
+    setMobileOpen(false);
+  }, []);
+
+  useEffect(() => {
+    if (mobileOpen || !restoreFocusRef.current) return;
+    restoreFocusRef.current = false;
+    triggerRef.current?.focus({ preventScroll: true });
+  }, [mobileOpen]);
+
+  useEffect(() => {
+    if (!mobileOpen) return;
+    const query = window.matchMedia("(max-width: 1080px)");
+    if (!query.matches) return;
+    const previousOverflow = document.body.style.overflow;
+    const focusFrame = window.requestAnimationFrame(() => {
+      closeRef.current?.focus({ preventScroll: true });
+    });
+    const onKeyDown = (event: KeyboardEvent) => {
+      if (event.key === "Escape") closeMobile(true);
+    };
+    const onChange = () => {
+      if (!query.matches) setMobileOpen(false);
+    };
+    document.body.style.overflow = "hidden";
+    window.addEventListener("keydown", onKeyDown);
+    query.addEventListener("change", onChange);
+    return () => {
+      window.cancelAnimationFrame(focusFrame);
+      document.body.style.overflow = previousOverflow;
+      window.removeEventListener("keydown", onKeyDown);
+      query.removeEventListener("change", onChange);
+    };
+  }, [closeMobile, mobileOpen]);
+
+  const isOverview = currentPath === "";
+
+  return (
+    <>
+      <div className="gdoc-mobile-bar" aria-label="说明书目录栏">
+        <button
+          ref={triggerRef}
+          type="button"
+          className="gdoc-mobile-trigger"
+          aria-controls={drawerId}
+          aria-expanded={mobileOpen}
+          onClick={() => setMobileOpen(true)}
+        >
+          <List size={16} weight="bold" aria-hidden="true" />
+          <span>说明目录</span>
+        </button>
+        <a
+          className="gdoc-nojs-trigger"
+          id={`${drawerId}-open`}
+          href={`#${drawerId}`}
+          aria-label="打开说明目录"
+        >
+          <List size={16} weight="bold" aria-hidden="true" />
+          <span>说明目录</span>
+        </a>
+        <div className="gdoc-mobile-crumb" aria-hidden="true">
+          <span>{currentSection?.title ?? "Garden 使用说明"}</span>
+          <CaretRight size={12} />
+          <strong>{currentDoc ? (NAV_SHORT_TITLE[currentDoc.path] ?? currentDoc.title) : "总览与快速入口"}</strong>
+        </div>
+      </div>
+
+      <button
+        type="button"
+        className="gdoc-backdrop"
+        aria-label="关闭说明目录"
+        tabIndex={mobileOpen ? 0 : -1}
+        data-open={mobileOpen}
+        onClick={() => closeMobile(true)}
+      />
+
+      <aside
+        id={drawerId}
+        className="gdoc-sidebar"
+        aria-label="Garden 使用说明目录"
+        data-open={mobileOpen}
+      >
+        <div className="gdoc-sidebar-head">
+          <Link
+            href={siteHref("/garden")}
+            className="gdoc-overview-link"
+            aria-current={isOverview ? "page" : undefined}
+            onClick={() => closeMobile(false)}
+          >
+            <span className="gdoc-overview-mark">
+              <BookOpenText size={16} weight="duotone" aria-hidden="true" />
+              <span>Garden 使用说明</span>
+            </span>
+            <small>总览与快速入口</small>
+          </Link>
+          <button
+            ref={closeRef}
+            type="button"
+            className="gdoc-mobile-close"
+            aria-label="关闭说明目录"
+            onClick={() => closeMobile(true)}
+          >
+            <X size={17} aria-hidden="true" />
+          </button>
+          <a
+            className="gdoc-nojs-close"
+            href={`#${drawerId}-open`}
+            aria-label="关闭说明目录"
+          >
+            <X size={17} aria-hidden="true" />
+          </a>
+        </div>
+
+        <nav className="gdoc-nav" aria-label="章节导航">
+          {groups.map((group) => (
+            <div key={group.id} className="gdoc-nav-group">
+              <div className="gdoc-nav-group-head">
+                <h2>{group.title}</h2>
+                {group.note ? <span>{group.note}</span> : null}
+              </div>
+              <ol className="gdoc-nav-list">
+                {group.items.map((item) => {
+                  const active = item.path === currentPath;
+                  const badge = COMPONENT_BADGE[item.path];
+                  const label = NAV_SHORT_TITLE[item.path] ?? item.title;
+                  return (
+                    <li key={item.path} className={active ? "is-active" : undefined}>
+                      <Link
+                        href={siteHref(`/garden/${item.path}`)}
+                        aria-current={active ? "page" : undefined}
+                        onClick={() => closeMobile(false)}
+                      >
+                        {badge ? (
+                          <>
+                            <code className="gdoc-comp-pill">{badge}</code>
+                            <span className="gdoc-comp-label">{label}</span>
+                          </>
+                        ) : (
+                          <span>{label}</span>
+                        )}
+                      </Link>
+                    </li>
+                  );
+                })}
+              </ol>
+            </div>
+          ))}
+        </nav>
+      </aside>
+    </>
+  );
+}

package/app/components/MarkdownArticle.tsx

@@ -8,7 +8,7 @@ import {
   type HTMLAttributes,
   type ReactNode,
 } from "react";
-import { articleHeadingBase, articleUsesHeadingNumbers, displayHeadingLevel, splitHeadingNumber } from "../lib/content";
+import { articleHeadingBase, autoNumbersHeadings, displayHeadingLevel, splitHeadingNumber } from "../lib/content";
 import Link from "next/link";
 import ReactMarkdown from "react-markdown";
 import rehypeRaw from "rehype-raw";
@@ -28,7 +28,7 @@ import { imageDimensions, lookupImageSize } from "../../ui/garden/image-dims.mjs
 import { siteConfig, siteLinks } from "@garden/site-config";
 import { articleLink, sameSiteMatcher } from "../../ui/garden/same-site.mjs";
 import { columnRedirects, internalLinkResolver, readRedirects } from "../../ui/garden/internal-links.mjs";
-import { columnHref, columns, postHref, posts, thoughts } from "../lib/content";
+import { columnHref, columns, gardenDocHref, gardenDocs, postHref, posts, thoughts } from "../lib/content";
 import { LinkCardRefresh } from "./LinkCardRefresh";
 import { linkHost } from "../../scripts/link-meta-core.mjs";
 import { cardDate } from "../../ui/garden/card-refresh.mjs";
@@ -46,10 +46,11 @@ const internalRoute = internalLinkResolver({
     ...columnRedirects({ columns: [...new Set(columns.map((entry) => entry.column).filter(Boolean))].map((slug) => ({ slug })) }),
   ],
   routes: [
-    "/", "/blog", "/columns", "/thoughts", "/tags", "/about",
+    "/", "/blog", "/columns", "/thoughts", "/tags", "/about", "/garden",
     ...posts.map(postHref),
     ...columns.map(columnHref),
     ...thoughts.map((thought) => `/thoughts/${thought.slug}`),
+    ...gardenDocs.map(gardenDocHref),
   ],
   basePath: siteLinks?.basePath ?? "",
   // Same shape as every other address in the site (the slash follows trailingSlash).
@@ -207,11 +208,11 @@ const headingText = (children: ReactNode) => {
   return parts.join("");
 };
 
-export function MarkdownArticle({ content }: { content: string }) {
+export function MarkdownArticle({ content, numbering }: { content: string; numbering?: boolean }) {
   // Optional layer 2: a Worker that refreshes card text. Without it, cards stay as built.
   const cardWorker = content.includes("{card}") ? siteConfig.linkPreview?.worker : undefined;
   const numbers = { h2: 0, h3: 0 };
-  const numberedArticle = articleUsesHeadingNumbers(content);
+  const autoNumber = autoNumbersHeadings(content, numbering);
   const headingBase = articleHeadingBase(content);
   const section = (depth: 2 | 3, children: ReactNode) => {
     const raw = headingText(children).trim();
@@ -222,7 +223,7 @@ export function MarkdownArticle({ content }: { content: string }) {
       const prefix = raw.slice(0, raw.length - split.text.length);
       return { no: split.no, children: stripPrefix(children, prefix) };
     }
-    if (numberedArticle) return { no: "", children };
+    if (!autoNumber) return { no: "", children };
     if (depth === 2) { numbers.h2 += 1; numbers.h3 = 0; return { no: String(numbers.h2), children }; }
     numbers.h3 += 1;
     return { no: numbers.h2 ? `${numbers.h2}.${numbers.h3}` : String(numbers.h3), children };

package/app/components/SiteChrome.tsx

@@ -12,7 +12,7 @@ export function SiteChrome({ children }: { children: React.ReactNode }) {
     <>
       <SiteHeader />
       <div id="main-content">{children}</div>
-      <SiteFooter />
+      <SiteFooter docs={pathname?.startsWith("/garden") ?? false} />
     </>
   );
 }

package/app/components/SiteFooter.tsx

@@ -1,13 +1,20 @@
 import { GithubLogo, Rss } from "@phosphor-icons/react/ssr";
 import { githubUrl, siteConfig } from "../site.config";
 
-export function SiteFooter() {
+/** On the Garden docs pages the footer carries no site-owner line. */
+export function SiteFooter({ docs = false }: { docs?: boolean }) {
   return (
     <footer className="sh-footer">
       <div className="sh-foot">
         <p>
-          © {new Date().getFullYear()} {siteConfig.author.name} · {siteConfig.footer}
-          <span className="footer-framework"> · 基于 <a href="https://github.com/hedon954/garden" target="_blank" rel="noreferrer">Garden</a> 构建</span>
+          {docs ? (
+            <span className="footer-framework">基于 <a href="https://github.com/hedon954/garden" target="_blank" rel="noreferrer">Garden</a> 构建</span>
+          ) : (
+            <>
+              © {new Date().getFullYear()} {siteConfig.author.name} · {siteConfig.footer}
+              <span className="footer-framework"> · 基于 <a href="https://github.com/hedon954/garden" target="_blank" rel="noreferrer">Garden</a> 构建</span>
+            </>
+          )}
         </p>
         <div className="sh-foot-links">
           <a href={githubUrl} rel="me">

package/app/garden/[...slug]/page.tsx

@@ -0,0 +1,148 @@
+import Link from "next/link";
+import type { Metadata } from "next";
+import { notFound } from "next/navigation";
+import { ArrowLeft, ArrowRight } from "@phosphor-icons/react/ssr";
+import {
+  extractHeadings,
+  findGardenDoc,
+  gardenDocHref,
+  gardenDocs,
+} from "../../lib/content";
+import { FEED_ALTERNATES } from "../../lib/page-alternates";
+import { absoluteUrl, getSiteUrl } from "../../lib/site";
+import { siteHref } from "../../lib/site-href";
+import { ArticleMeasure } from "../../components/ArticleMeasure";
+import { ArticleReferences } from "../../components/ArticleReferences";
+import { ArticleTitle } from "../../components/ArticleTitle";
+import { MarkdownArticle } from "../../components/MarkdownArticle";
+import { TableOfContents } from "../../components/TableOfContents";
+import { GardenDocsNav } from "../../components/GardenDocsNav";
+import {
+  COMPONENT_BADGE,
+  HANDBOOK_SECTIONS,
+  orderedHandbookDocs,
+  toHandbookNavItems,
+} from "../../lib/garden-docs-meta";
+import {
+  isStaticPlaceholder,
+  STATIC_PLACEHOLDER,
+  staticParams,
+} from "../../../ui/garden/static-params.mjs";
+
+export function generateStaticParams() {
+  return staticParams(
+    gardenDocs.map((doc) => ({ slug: doc.path.split("/") })),
+    { slug: [STATIC_PLACEHOLDER] },
+  );
+}
+
+export async function generateMetadata({
+  params,
+}: {
+  params: Promise<{ slug: string[] }>;
+}) {
+  const { slug } = await params;
+  const doc = findGardenDoc(slug.join("/"));
+  if (!doc) return {};
+  const baseUrl = await getSiteUrl();
+  const pathname = gardenDocHref(doc);
+  return {
+    title: `${doc.title} · Garden 使用说明`,
+    description: doc.description,
+    alternates: { canonical: pathname, types: FEED_ALTERNATES },
+    openGraph: {
+      type: "article",
+      url: absoluteUrl(pathname, baseUrl),
+      title: `${doc.title} · Garden 使用说明`,
+      description: doc.description,
+    },
+  } satisfies Metadata;
+}
+
+export default async function GardenDocPage({
+  params,
+}: {
+  params: Promise<{ slug: string[] }>;
+}) {
+  const { slug } = await params;
+  const doc = findGardenDoc(slug.join("/"));
+  if (!doc) {
+    if (isStaticPlaceholder(slug)) return null;
+    notFound();
+  }
+
+  const ordered = orderedHandbookDocs(gardenDocs);
+  const navItems = toHandbookNavItems(gardenDocs);
+  const index = ordered.findIndex((item) => item.path === doc.path);
+  const prev = index > 0 ? ordered[index - 1] : null;
+  const next = index >= 0 && index < ordered.length - 1 ? ordered[index + 1] : null;
+  const headings = extractHeadings(doc.content);
+  const sectionMeta = HANDBOOK_SECTIONS.find((sec) => sec.id === doc.section);
+  const componentBadge = COMPONENT_BADGE[doc.path];
+
+  return (
+    <main className="column-reading-page garden-doc-page">
+      <GardenDocsNav docs={navItems} currentPath={doc.path} />
+
+      <article className="article-column garden-doc-article h-entry">
+        <header className="gdoc-article-head">
+          <div className="gdoc-eyebrow">
+            <Link href={siteHref("/garden")} className="gdoc-eyebrow-root">
+              Garden 使用说明
+            </Link>
+            <span aria-hidden="true">/</span>
+            <span>{sectionMeta?.title ?? doc.sectionTitle ?? "指南"}</span>
+            {componentBadge ? (
+              <>
+                <code className="gdoc-eyebrow-fence">{`garden ${componentBadge}`}</code>
+              </>
+            ) : null}
+          </div>
+          <ArticleTitle title={doc.title} />
+          {doc.description ? (
+            <p className="gdoc-article-deck p-summary">{doc.description}</p>
+          ) : null}
+        </header>
+
+        <ArticleMeasure />
+
+        <div className="e-content">
+          <MarkdownArticle content={doc.content} />
+        </div>
+
+        <ArticleReferences references={doc.references} />
+
+        <nav className="gdoc-pager" aria-label="说明书上下篇导航">
+          {prev ? (
+            <Link href={gardenDocHref(prev)} className="gdoc-pager-card is-prev">
+              <span className="gdoc-pager-dir">
+                <ArrowLeft size={14} aria-hidden="true" />
+                上一篇
+              </span>
+              <strong>{prev.title}</strong>
+            </Link>
+          ) : (
+            <Link href={siteHref("/garden")} className="gdoc-pager-card is-prev">
+              <span className="gdoc-pager-dir">
+                <ArrowLeft size={14} aria-hidden="true" />
+                返回总览
+              </span>
+              <strong>Garden 使用说明首页</strong>
+            </Link>
+          )}
+          {next ? (
+            <Link href={gardenDocHref(next)} className="gdoc-pager-card is-next">
+              <span className="gdoc-pager-dir">
+                下一篇
+                <ArrowRight size={14} aria-hidden="true" />
+              </span>
+              <strong>{next.title}</strong>
+            </Link>
+          ) : null}
+        </nav>
+      </article>
+
+      <TableOfContents headings={headings} label="本页目录" />
+    </main>
+  );
+}