hd-garden 0.7.0 → 0.8.1

package/app/components/HandbookView.tsx

@@ -0,0 +1,270 @@
+import Link from "next/link";
+import type { Metadata } from "next";
+import { ArrowLeft, ArrowRight } from "@phosphor-icons/react/ssr";
+import { ArticleMeasure } from "./ArticleMeasure";
+import { ArticleReferences } from "./ArticleReferences";
+import { ArticleTitle } from "./ArticleTitle";
+import { GardenDocsNav } from "./GardenDocsNav";
+import { HandbookLangRedirect } from "./HandbookLangRedirect";
+import { MarkdownArticle } from "./MarkdownArticle";
+import { TableOfContents } from "./TableOfContents";
+import { extractHeadings, handbookDocs, handbookIndexDoc, hasHandbookPage, type GardenDocEntry } from "../lib/content";
+import { pageAlternates } from "../lib/page-alternates";
+import { absoluteUrl, getSiteUrl } from "../lib/site";
+import { siteHref } from "../lib/site-href";
+import {
+  COMPONENT_BADGE,
+  HANDBOOK_SECTIONS,
+  HANDBOOK_UI,
+  handbookPath,
+  isReferencePath,
+  orderedHandbookDocs,
+  sectionTitle,
+  toHandbookNavItems,
+  type HandbookLang,
+} from "../lib/garden-docs-meta";
+import { UI_STRINGS, siteLang } from "../lib/i18n";
+import { siteConfig } from "../site.config";
+
+const other = (lang: HandbookLang): HandbookLang => (lang === "en" ? "zh" : "en");
+const hreflang = (lang: HandbookLang) => (lang === "en" ? "en" : "zh-CN");
+
+/** canonical + hreflang links; the counterpart is listed only when it exists. */
+export function handbookLanguages(lang: HandbookLang, docPath: string) {
+  if (siteLang === "en") return undefined;
+  if (!hasHandbookPage(other(lang), docPath)) return undefined;
+  const zh = siteHref(handbookPath("zh", docPath));
+  const en = siteHref(handbookPath("en", docPath));
+  return { "zh-CN": zh, en, "x-default": zh };
+}
+
+export const handbookAlternates = (lang: HandbookLang, docPath: string) =>
+  pageAlternates(handbookPath(lang, docPath), handbookLanguages(lang, docPath));
+
+export async function handbookOverviewMetadata(lang: HandbookLang, indexDoc: GardenDocEntry | null | undefined) {
+  const t = HANDBOOK_UI[lang];
+  const baseUrl = await getSiteUrl();
+  const pathname = siteHref(handbookPath(lang, "index"));
+  const description = indexDoc?.description ?? "";
+  const fullTitle = `${t.name} · ${siteConfig.name}`;
+  const imageAlt =
+    lang === "en"
+      ? `${siteConfig.name} · ${indexDoc?.title || t.name}`
+      : `${siteConfig.name} · ${siteConfig.pages.home.title.replace("\n", "")}`;
+  return {
+    title: t.name,
+    description,
+    alternates: pageAlternates(handbookPath(lang), handbookLanguages(lang, "index")),
+    openGraph: {
+      type: "website",
+      url: absoluteUrl(pathname, baseUrl),
+      title: fullTitle,
+      description,
+      locale: lang === "en" ? "en_US" : "zh_CN",
+      images: [
+        {
+          url: "/og.png",
+          width: 1731,
+          height: 909,
+          alt: imageAlt,
+        },
+      ],
+    },
+    twitter: {
+      card: "summary_large_image",
+      title: fullTitle,
+      description,
+      images: ["/og.png"],
+    },
+  } satisfies Metadata;
+}
+
+export async function handbookDocMetadata(lang: HandbookLang, doc: GardenDocEntry | undefined) {
+  if (!doc) {
+    const copy = UI_STRINGS[lang];
+    const fullTitle = `${copy.notFoundTitle} · ${siteConfig.name}`;
+    return {
+      title: copy.notFoundTitle,
+      description: copy.notFoundDeck,
+      openGraph: {
+        type: "website",
+        title: fullTitle,
+        description: copy.notFoundDeck,
+        locale: lang === "en" ? "en_US" : "zh_CN",
+        images: [
+          {
+            url: "/og.png",
+            width: 1731,
+            height: 909,
+            alt: fullTitle,
+          },
+        ],
+      },
+      twitter: {
+        card: "summary_large_image",
+        title: fullTitle,
+        description: copy.notFoundDeck,
+        images: ["/og.png"],
+      },
+    } satisfies Metadata;
+  }
+  const t = HANDBOOK_UI[lang];
+  const baseUrl = await getSiteUrl();
+  const pathname = siteHref(handbookPath(lang, doc.path));
+  const docTitle = `${doc.title} · ${t.name}`;
+  return {
+    title: docTitle,
+    description: doc.description,
+    alternates: handbookAlternates(lang, doc.path),
+    openGraph: {
+      type: "article",
+      url: absoluteUrl(pathname, baseUrl),
+      title: docTitle,
+      description: doc.description,
+      locale: lang === "en" ? "en_US" : "zh_CN",
+      images: [
+        {
+          url: "/og.png",
+          width: 1731,
+          height: 909,
+          alt: `${siteConfig.name} · ${docTitle}`,
+        },
+      ],
+    },
+    twitter: {
+      card: "summary_large_image",
+      title: docTitle,
+      description: doc.description,
+      images: ["/og.png"],
+    },
+  } satisfies Metadata;
+}
+
+export function HandbookOverview({ lang }: { lang: HandbookLang }) {
+  const t = HANDBOOK_UI[lang];
+  const docs = handbookDocs(lang);
+  const indexDoc = handbookIndexDoc(lang);
+  const navItems = toHandbookNavItems(docs);
+  const firstDoc = orderedHandbookDocs(docs)[0] ?? null;
+  const content = indexDoc?.content ?? "";
+  const headings = extractHeadings(content);
+  // The site config title/subtitle is written in the site's own language.
+  const configured = lang === siteLang ? siteConfig.pages.garden : { title: "", subtitle: "" };
+  const title = configured.title?.trim() || indexDoc?.title || t.name;
+  const subtitle = configured.subtitle?.trim() || indexDoc?.description || "";
+
+  return (
+    <main className="column-reading-page garden-doc-page" lang={hreflang(lang)}>
+      <HandbookLangRedirect lang={lang} />
+      <GardenDocsNav docs={navItems} currentPath="" lang={lang} />
+
+      <article className="article-column garden-doc-article h-entry">
+        <header className="gdoc-article-head">
+          <div className="gdoc-eyebrow">
+            <span>{t.name}</span>
+            <span aria-hidden="true">/</span>
+            <span>{t.overview}</span>
+          </div>
+          <ArticleTitle title={title} />
+          {subtitle ? <p className="gdoc-article-deck p-summary">{subtitle}</p> : null}
+        </header>
+
+        <ArticleMeasure />
+
+        <div className="e-content">
+          <MarkdownArticle content={content} lang={lang} fieldTables handbook />
+        </div>
+
+        <ArticleReferences references={indexDoc?.references} lang={lang} />
+
+        {firstDoc ? (
+          <nav className="gdoc-pager" aria-label={t.pager}>
+            <Link href={siteHref(handbookPath(lang, firstDoc.path))} className="gdoc-pager-card is-next">
+              <span className="gdoc-pager-dir">
+                {t.next}
+                <ArrowRight size={14} aria-hidden="true" />
+              </span>
+              <strong>{firstDoc.title}</strong>
+            </Link>
+          </nav>
+        ) : null}
+      </article>
+
+      <TableOfContents headings={headings} label={t.toc} lang={lang} />
+    </main>
+  );
+}
+
+export function HandbookDoc({ lang, doc }: { lang: HandbookLang; doc: GardenDocEntry }) {
+  const t = HANDBOOK_UI[lang];
+  const docs = handbookDocs(lang);
+  const ordered = orderedHandbookDocs(docs);
+  const navItems = toHandbookNavItems(docs);
+  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${isReferencePath(doc.path) ? " is-reference" : ""}`} lang={hreflang(lang)}>
+      <HandbookLangRedirect lang={lang} />
+      <GardenDocsNav docs={navItems} currentPath={doc.path} lang={lang} />
+
+      <article className="article-column garden-doc-article h-entry">
+        <header className="gdoc-article-head">
+          <div className="gdoc-eyebrow">
+            <Link href={siteHref(handbookPath(lang))} className="gdoc-eyebrow-root">
+              {t.name}
+            </Link>
+            <span aria-hidden="true">/</span>
+            <span>{sectionTitle(sectionMeta, lang) ?? doc.sectionTitle ?? t.guide}</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} lang={lang} fieldTables handbook refDemos={isReferencePath(doc.path)} />
+        </div>
+
+        <ArticleReferences references={doc.references} lang={lang} />
+
+        <nav className="gdoc-pager" aria-label={t.pager}>
+          {prev ? (
+            <Link href={siteHref(handbookPath(lang, prev.path))} className="gdoc-pager-card is-prev">
+              <span className="gdoc-pager-dir">
+                <ArrowLeft size={14} aria-hidden="true" />
+                {t.prev}
+              </span>
+              <strong>{prev.title}</strong>
+            </Link>
+          ) : (
+            <Link href={siteHref(handbookPath(lang))} className="gdoc-pager-card is-prev">
+              <span className="gdoc-pager-dir">
+                <ArrowLeft size={14} aria-hidden="true" />
+                {t.backToOverview}
+              </span>
+              <strong>{t.overviewDocTitle}</strong>
+            </Link>
+          )}
+          {next ? (
+            <Link href={siteHref(handbookPath(lang, next.path))} className="gdoc-pager-card is-next">
+              <span className="gdoc-pager-dir">
+                {t.next}
+                <ArrowRight size={14} aria-hidden="true" />
+              </span>
+              <strong>{next.title}</strong>
+            </Link>
+          ) : null}
+        </nav>
+      </article>
+
+      <TableOfContents headings={headings} label={t.toc} lang={lang} />
+    </main>
+  );
+}

package/app/components/MarkdownArticle.tsx

@@ -1,3 +1,5 @@
+import { UiLangProvider } from "./UiLang";
+import { siteLang, ui, type UiLang } from "../lib/i18n";
 import { markdownPlugins } from "../lib/markdown-plugins";
 import { remarkA2 } from "../lib/remark-a2.mjs";
 import { remarkLinkCard } from "../lib/remark-link-card.mjs";
@@ -22,15 +24,19 @@ import { CodeCopy } from "./garden/chrome";
 import { CodeDiff } from "./garden/chrome";
 import { GardenBlock } from "./garden/GardenBlock";
 import { GardenFile } from "./garden/GardenFile";
+import { RefDemo } from "./garden/RefDemo";
+import { remarkRefDemos } from "../lib/remark-ref-demos.mjs";
 import { readGardenPayload } from "../lib/remark-garden.mjs";
 import { imageSizes, linkAssets } from "@garden/generated-content";
 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, gardenDocHref, gardenDocs, postHref, posts, thoughts } from "../lib/content";
+import { columnHref, columns, gardenDocHref, gardenDocs, gardenDocsEn, postHref, posts, thoughts } from "../lib/content";
 import { LinkCardRefresh } from "./LinkCardRefresh";
 import { linkHost } from "../../scripts/link-meta-core.mjs";
+import { FaviconProvider, SourceMark } from "./garden/patterns";
+import { rehypeFieldTables } from "../lib/rehype-field-tables.mjs";
 import { cardDate } from "../../ui/garden/card-refresh.mjs";
 import { siteHref } from "../lib/site-href";
 import { codeLanguageLabel, fenceLanguage } from "../../ui/garden/code-language.mjs";
@@ -40,23 +46,36 @@ const sameSite = sameSiteMatcher(siteLinks?.address ?? "", siteLinks?.basePath ?
 
 // Links to other pages of the site render as Link. A link to an old address listed under
 // redirects is rewritten to the page it moved to; a link that lands on no known page stays a plain anchor.
-const internalRoute = internalLinkResolver({
+const siteRoute = internalLinkResolver({
   redirects: [
     ...readRedirects(siteConfig),
     ...columnRedirects({ columns: [...new Set(columns.map((entry) => entry.column).filter(Boolean))].map((slug) => ({ slug })) }),
   ],
   routes: [
-    "/", "/blog", "/columns", "/thoughts", "/tags", "/about", "/garden",
+    "/", "/blog", "/columns", "/thoughts", "/tags", "/about", "/garden", "/garden/en",
     ...posts.map(postHref),
     ...columns.map(columnHref),
     ...thoughts.map((thought) => `/thoughts/${thought.slug}`),
     ...gardenDocs.map(gardenDocHref),
+    ...gardenDocsEn.map((doc) => siteHref(`/garden/en/${doc.path}`)),
   ],
   basePath: siteLinks?.basePath ?? "",
   // Same shape as every other address in the site (the slash follows trailingSlash).
   format: siteHref,
 });
 
+// The handbook ships with the framework and its links are written without
+// any base path (/garden/…); Link adds the site's own prefix.
+const handbookRoute = internalLinkResolver({
+  redirects: [],
+  routes: [
+    "/garden", "/garden/en",
+    ...gardenDocs.map(gardenDocHref),
+    ...gardenDocsEn.map((doc) => siteHref(`/garden/en/${doc.path}`)),
+  ],
+  format: siteHref,
+});
+
 /** The site's favicon, downloaded at build time; nothing when there is none. */
 function Favicon({ href }: { href: string }) {
   const src = linkAssets?.favicons?.[linkHost(href)];
@@ -208,7 +227,9 @@ const headingText = (children: ReactNode) => {
   return parts.join("");
 };
 
-export function MarkdownArticle({ content, numbering }: { content: string; numbering?: boolean }) {
+export function MarkdownArticle({ content, numbering, lang, fieldTables, refDemos, handbook }: { content: string; numbering?: boolean; lang?: UiLang; fieldTables?: boolean; refDemos?: boolean; handbook?: boolean }) {
+  const internalRoute = handbook ? handbookRoute : siteRoute;
+  const t = ui(lang);
   // 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 };
@@ -248,9 +269,10 @@ export function MarkdownArticle({ content, numbering }: { content: string; numbe
     "garden-block": (props: { dataPayload?: string; "data-payload"?: string }) => {
       const payload = props.dataPayload ?? props["data-payload"];
       const block = readGardenPayload(payload);
-      if (block?.name === "file" && !block.error) return <GardenFile props={(block.props ?? {}) as Record<string, unknown>} />;
+      if (block?.name === "file" && !block.error) return <GardenFile props={(block.props ?? {}) as Record<string, unknown>} lang={lang} />;
       return <GardenBlock dataPayload={payload} />;
     },
+    "garden-refdemo": (props: { children?: ReactNode; "data-name"?: string }) => <RefDemo lang={lang === "en" ? "en" : "zh"} name={props["data-name"]}>{props.children}</RefDemo>,
     "garden-codediff": (props: {
       children?: ReactNode;
       dataDiff?: string;
@@ -266,9 +288,11 @@ export function MarkdownArticle({ content, numbering }: { content: string; numbe
     ),
   };
   return (
+    <UiLangProvider lang={lang}>
+    <FaviconProvider favicons={linkAssets?.favicons}>
     <div className="markdown-body prose">
       <ReactMarkdown
-        remarkPlugins={[...markdownPlugins, [remarkLinkCard, { sameSite }], [remarkA2, { imageSize: (src: string) => lookupImageSize(imageSizes, src) }]]}
+        remarkPlugins={[...(refDemos ? [remarkRefDemos] : []), ...markdownPlugins, [remarkLinkCard, { sameSite }], [remarkA2, { imageSize: (src: string) => lookupImageSize(imageSizes, src), lang: lang ?? siteLang }]]}
         rehypePlugins={[
           rehypeRaw,
           rehypeKatex,
@@ -276,6 +300,8 @@ export function MarkdownArticle({ content, numbering }: { content: string; numbe
           // Not rehype-autolink-headings "wrap": a heading with a link in it would nest <a> in <a> (React #418).
           [rehypeHeadingAnchors, { className: ["h-anchor"] }],
           rehypeHighlight,
+          // Handbook only: field tables become cards on narrow screens.
+          ...(fieldTables ? [rehypeFieldTables] : []),
         ]}
         components={{
           p: ({ children, ...props }) => {
@@ -307,10 +333,12 @@ export function MarkdownArticle({ content, numbering }: { content: string; numbe
                 href={href}
                 {...domProps}
                 {...(external
-                  ? { className: "ext", target: "_blank", rel: "noopener noreferrer" }
+                  ? { ...(domProps.className ? { className: `ext ${domProps.className}` } : { className: "ext" }), target: "_blank", rel: "noopener noreferrer" }
                   : {})}
               >
-                {external && href ? <WithFavicon href={href}>{children}</WithFavicon> : children}
+                {external && href && /\bg-src-chip\b/u.test(String(domProps.className ?? ""))
+                  ? <><SourceMark href={href} /><span>{children}</span></>
+                  : <>{external && href ? <WithFavicon href={href}>{children}</WithFavicon> : children}</>}
               </a>
             );
           },
@@ -320,7 +348,7 @@ export function MarkdownArticle({ content, numbering }: { content: string; numbe
             return <MarkdownImage {...props} {...dims} style={{ ...props.style, ...dims.style }} />;
           },
           table: ({ children, ...props }) => (
-            <div className="table-wrap" role="region" aria-label="表格，可横向滚动" tabIndex={0}>
+            <div className={/\bfield-table\b/u.test(String(props.className ?? "")) ? "table-wrap field-wrap" : "table-wrap"} role="region" aria-label={t.tableScroll} tabIndex={0}>
               <table {...props}>{children}</table>
             </div>
           ),
@@ -356,5 +384,7 @@ export function MarkdownArticle({ content, numbering }: { content: string; numbe
       </ReactMarkdown>
       {cardWorker ? <LinkCardRefresh endpoint={cardWorker} /> : null}
     </div>
+    </FaviconProvider>
+    </UiLangProvider>
   );
 }

package/app/components/MarkdownImage.tsx

@@ -1,5 +1,6 @@
 "use client";
 
+import { useUi } from "./UiLang";
 import { useEffect, useState, type ComponentPropsWithoutRef } from "react";
 
 // react-markdown also hands over its syntax-tree `node`; it must not reach the DOM.
@@ -8,7 +9,8 @@ type MarkdownImageProps = ComponentPropsWithoutRef<"img"> & { node?: unknown };
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
 export function MarkdownImage({ alt = "", src, node, style, ...props }: MarkdownImageProps) {
   const [open, setOpen] = useState(false);
-  const description = alt || "查看原图";
+  const t = useUi();
+  const description = alt || t.viewImage;
 
   useEffect(() => {
     if (!open) return undefined;
@@ -33,7 +35,7 @@ export function MarkdownImage({ alt = "", src, node, style, ...props }: Markdown
         type="button"
         className="markdown-image-trigger"
         onClick={() => setOpen(true)}
-        aria-label={`放大查看：${description}`}
+        aria-label={t.zoomImage(description)}
       >
         {/* Native images preserve Typora-authored relative paths. */}
         {/* eslint-disable-next-line @next/next/no-img-element */}
@@ -56,9 +58,9 @@ export function MarkdownImage({ alt = "", src, node, style, ...props }: Markdown
               type="button"
               className="markdown-image-lightbox-close"
               onClick={() => setOpen(false)}
-              aria-label="关闭图片预览"
+              aria-label={t.closeImage}
             >
-              关闭
+              {t.close.trim()}
             </button>
           </div>
         </div>

package/app/components/SiteChrome.tsx

@@ -1,18 +1,27 @@
 "use client";
 
 import { usePathname } from "next/navigation";
+import { inAppPath, isHandbookPath, routeLang, ui } from "../lib/i18n";
 import { SiteFooter } from "./SiteFooter";
 import { SiteHeader } from "./SiteHeader";
 
 export function SiteChrome({ children }: { children: React.ReactNode }) {
   const pathname = usePathname();
-  if (pathname?.startsWith("/admin")) return <>{children}</>;
+  const lang = routeLang(pathname);
+  // The skip link follows the route language too (/garden/en/ is English).
+  const skip = (
+    <a className="skip-link" href="#main-content">
+      {ui(lang).skipToContent}
+    </a>
+  );
+  if (inAppPath(pathname).startsWith("/admin")) return <>{skip}{children}</>;
 
   return (
     <>
+      {skip}
       <SiteHeader />
       <div id="main-content">{children}</div>
-      <SiteFooter docs={pathname?.startsWith("/garden") ?? false} />
+      <SiteFooter docs={isHandbookPath(pathname)} lang={lang} />
     </>
   );
 }

package/app/components/SiteFooter.tsx

@@ -1,18 +1,20 @@
 import { GithubLogo, Rss } from "@phosphor-icons/react/ssr";
 import { githubUrl, siteConfig } from "../site.config";
+import { ui, type UiLang } from "../lib/i18n";
 
 /** On the Garden docs pages the footer carries no site-owner line. */
-export function SiteFooter({ docs = false }: { docs?: boolean }) {
+export function SiteFooter({ docs = false, lang }: { docs?: boolean; lang?: UiLang }) {
+  const t = ui(lang);
   return (
     <footer className="sh-footer">
       <div className="sh-foot">
         <p>
           {docs ? (
-            <span className="footer-framework">基于 <a href="https://github.com/hedon954/garden" target="_blank" rel="noreferrer">Garden</a> 构建</span>
+            <span className="footer-framework">{t.builtWith[0]}<a href="https://github.com/hedon954/garden" target="_blank" rel="noreferrer">Garden</a>{t.builtWith[1]}</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>
+              <span className="footer-framework"> · {t.builtWith[0]}<a href="https://github.com/hedon954/garden" target="_blank" rel="noreferrer">Garden</a>{t.builtWith[1]}</span>
             </>
           )}
         </p>
@@ -21,7 +23,7 @@ export function SiteFooter({ docs = false }: { docs?: boolean }) {
             <GithubLogo size={16} aria-hidden="true" />
             GitHub
           </a>
-          <a href="/rss.xml">
+          <a href={`${(process.env.NEXT_PUBLIC_BASE_PATH ?? "").replace(/\/+$/u, "")}/rss.xml`}>
             <Rss size={16} aria-hidden="true" />
             RSS
           </a>