hd-garden 0.5.0 → 0.5.1

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

@@ -1,4 +1,5 @@
 import Link from "next/link";
+import { CoverImage } from "../../components/CoverImage";
 import type { Metadata } from "next";
 import { notFound } from "next/navigation";
 import {
@@ -110,8 +111,7 @@ export default async function PostPage({
           <ArticleTags tags={post.tags} />
           {post.cover && (
             <figure className="article-hero article-cover cover-card cover-img">
-              {/* eslint-disable-next-line @next/next/no-img-element */}
-              <img className="u-photo" src={post.cover} alt={`${post.title} 封面`} />
+              <CoverImage className="u-photo" src={post.cover} image={post.coverImage} alt={`${post.title} 封面`} sizes="(max-width: 920px) calc(100vw - 40px), 880px" priority />
             </figure>
           )}
         </header>

package/app/blog/page.tsx

@@ -2,6 +2,7 @@ import { Suspense } from "react";
 import { siteConfig, siteDocumentTitle } from "../site.config";
 import { BlogArchive, BlogArchiveFallback } from "../components/BlogArchive";
 import { posts } from "../lib/content";
+import { archivePosts, archiveSeries } from "../lib/archive";
 
 export const metadata = {
   title: siteDocumentTitle,
@@ -9,14 +10,16 @@ export const metadata = {
 };
 
 export default function BlogIndex() {
+  const list = archivePosts();
+  const series = archiveSeries();
   return (
     <main className="sh-main" id="content">
       <div className="sh-head">
         <h1 id="sh-title">文章</h1>
         <p className="sh-deck">阶段性的完整沉淀，关于工程、架构与技术思考。共 {posts.length} 篇，按年份归档。</p>
       </div>
-      <Suspense fallback={<BlogArchiveFallback />}>
-        <BlogArchive />
+      <Suspense fallback={<BlogArchiveFallback posts={list} series={series} />}>
+        <BlogArchive posts={list} series={series} />
       </Suspense>
     </main>
   );

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

@@ -1,4 +1,5 @@
 import Link from "next/link";
+import { CoverImage } from "../../../components/CoverImage";
 import type { Metadata } from "next";
 import { notFound } from "next/navigation";
 import { ArrowLeft, ArrowRight } from "@phosphor-icons/react/ssr";
@@ -130,12 +131,7 @@ export default async function ColumnEntryPage({
           <ArticleTags tags={entry.tags} />
           {entry.cover && (
             <figure className="article-hero article-cover cover-img">
-              {/* eslint-disable-next-line @next/next/no-img-element */}
-              <img
-                className="u-photo"
-                src={entry.cover}
-                alt={`${entry.title} 封面`}
-              />
+              <CoverImage className="u-photo" src={entry.cover} image={entry.coverImage} alt={`${entry.title} 封面`} sizes="(max-width: 920px) calc(100vw - 40px), 880px" priority />
             </figure>
           )}
         </header>

package/app/components/ArticleReferences.tsx

@@ -1,6 +1,9 @@
+import { referenceColumns, referenceDomain } from "../../ui/garden/references.mjs";
+
 type ReferenceItem = {
   title: string;
   url?: string;
+  domain?: string;
 };
 
 export function ArticleReferences({
@@ -9,39 +12,36 @@ export function ArticleReferences({
   references?: ReferenceItem[];
 }) {
   if (!references?.length) return null;
+  const split = referenceColumns(references.length) === 2;
 
   return (
-    <section className="article-references" aria-labelledby="article-references-heading">
-      <p id="article-references-heading">参考</p>
-      <table>
-        <tbody>
-          {references.map((item, index) => {
-            const number = index + 1;
-            return (
-              <tr key={index}>
-                <td>
-                  {item.url ? (
-                    <a href={item.url} tabIndex={-1} aria-hidden="true">
-                      {number}
-                    </a>
-                  ) : (
-                    <span>{number}</span>
-                  )}
-                </td>
-                <td>
-                  {item.url ? (
-                    <a href={item.url} rel="noreferrer">
-                      <span>{item.title}</span>
-                    </a>
-                  ) : (
-                    <span>{item.title}</span>
-                  )}
-                </td>
-              </tr>
-            );
-          })}
-        </tbody>
-      </table>
+    <section
+      className={split ? "article-references is-split" : "article-references"}
+      aria-labelledby="article-references-heading"
+    >
+      <h2 id="article-references-heading">参考</h2>
+      <ol>
+        {references.map((item, index) => {
+          const domain = item.domain ?? referenceDomain(item.url);
+          return (
+            <li key={index}>
+              {item.url ? (
+                <a href={item.url} rel="noreferrer">
+                  {item.title}
+                </a>
+              ) : (
+                <span className="ref-title">{item.title}</span>
+              )}
+              {domain ? (
+                <>
+                  {" "}
+                  <span className="ref-domain">{domain}</span>
+                </>
+              ) : null}
+            </li>
+          );
+        })}
+      </ol>
     </section>
   );
 }

package/app/components/BlogArchive.tsx

@@ -3,9 +3,10 @@
 import Link from "next/link";
 import { usePathname, useRouter, useSearchParams } from "next/navigation";
 import { useMemo, useState } from "react";
-import { columnIndexHref, columnOfPost, columns, postHref, posts } from "../lib/content";
+import type { ArchivePost, ArchiveSeries } from "../lib/archive";
 import {
   TAG_PARAM,
+  canonicalTags,
   filterByTags,
   selectedTags,
   tagFilterHref,
@@ -27,35 +28,40 @@ function day(value: string) {
   }).format(date);
 }
 
-function ColumnLabel({ path }: { path: string }) {
-  const column = columnOfPost({ path });
+// Kept local: importing ../lib/content here would pull every post body into the client bundle.
+const postHref = (post: Pick<ArchivePost, "path">) => `/blog/${post.path}`;
+const columnIndexHref = (slug: string) => `/columns#${slug}`;
+
+function ColumnLabel({ column }: { column?: ArchivePost["column"] }) {
   return column ? <Link className="cat" href={columnIndexHref(column.slug)}>{column.title}</Link> : null;
 }
 
+type ArchiveData = { posts: ArchivePost[]; series: ArchiveSeries[] };
+
 const NO_TAGS: string[] = [];
 
 /** Reads the selected tags from the URL; needs a Suspense boundary. */
-export function BlogArchive() {
+export function BlogArchive({ posts, series }: ArchiveData) {
   const router = useRouter();
   const pathname = usePathname() || "/blog";
   const searchParams = useSearchParams();
   const paramKey = searchParams.getAll(TAG_PARAM).join("\u0000");
-  const selected = useMemo(() => selectedTags(paramKey ? paramKey.split("\u0000") : []), [paramKey]);
-  return <ArchiveView selected={selected} go={(next) => router.push(tagFilterHref(next, pathname), { scroll: false })} />;
+  const selected = useMemo(() => canonicalTags(posts, selectedTags(paramKey ? paramKey.split("\u0000") : [])), [paramKey, posts]);
+  return <ArchiveView posts={posts} series={series} selected={selected} go={(next) => router.push(tagFilterHref(next, pathname), { scroll: false })} />;
 }
 
 /**
  * The full, unfiltered list. Rendered into the static page as the Suspense
  * fallback, so the list is there before scripts run (or without them).
  */
-export function BlogArchiveFallback() {
-  return <ArchiveView selected={NO_TAGS} go={(next) => window.location.assign(tagFilterHref(next))} />;
+export function BlogArchiveFallback({ posts, series }: ArchiveData) {
+  return <ArchiveView posts={posts} series={series} selected={NO_TAGS} go={(next) => window.location.assign(tagFilterHref(next))} />;
 }
 
-function ArchiveView({ selected, go }: { selected: string[]; go: (next: string[]) => void }) {
+function ArchiveView({ posts, series, selected, go }: ArchiveData & { selected: string[]; go: (next: string[]) => void }) {
   const [compact, setCompact] = useState(false);
   const [expanded, setExpanded] = useState(false);
-  const options = useMemo(() => tagOptions(posts, selected), [selected]);
+  const options = useMemo(() => tagOptions(posts, selected), [posts, selected]);
   const { shown, hidden } = visibleTagOptions(options, expanded);
   const filtered = filterByTags(posts, selected)
     .slice()
@@ -68,16 +74,6 @@ function ArchiveView({ selected, go }: { selected: string[]; go: (next: string[]
     else years.set(year, [post]);
   }
 
-  const series = Array.from(
-    columns.reduce((result, entry) => {
-      const key = entry.column ?? "";
-      const list = result.get(key);
-      if (list) list.push(entry);
-      else result.set(key, [entry]);
-      return result;
-    }, new Map<string, typeof columns>()),
-  );
-
   return (
     <div className="sh-listgrid">
       <div>
@@ -126,17 +122,13 @@ function ArchiveView({ selected, go }: { selected: string[]; go: (next: string[]
                   <li className="sh-row" key={post.path}>
                     <time className="archive-meta" dateTime={day(post.date)}>{day(post.date).slice(5)}</time>
                     <div className="archive-copy">
-                      {post.cover ? (
-                        // eslint-disable-next-line @next/next/no-img-element
-                        <img className="archive-cover" src={post.cover} alt="" />
-                      ) : null}
                       <h3>
                         <Link href={postHref(post)}>{post.title}</Link>
                         {post.pinned ? <span className="pin">置顶</span> : null}
                       </h3>
                       {post.description ? <p>{post.description}</p> : null}
                     </div>
-                    <ColumnLabel path={post.path} />
+                    <ColumnLabel column={post.column} />
                   </li>
                 ))}
               </ol>
@@ -167,9 +159,9 @@ function ArchiveView({ selected, go }: { selected: string[]; go: (next: string[]
           <>
             <h2>专栏</h2>
             <ol>
-              {series.map(([slug, entries]) => (
-                <li key={slug}>
-                  <Link href={columnIndexHref(slug)}><span>{entries[0]?.columnTitle ?? slug}</span><span className="n num">{entries.length}</span></Link>
+              {series.map((column) => (
+                <li key={column.slug}>
+                  <Link href={columnIndexHref(column.slug)}><span>{column.title}</span><span className="n num">{column.count}</span></Link>
                 </li>
               ))}
             </ol>

package/app/components/CoverImage.tsx

@@ -0,0 +1,34 @@
+import type { ContentEntry } from "../lib/content";
+
+type CoverImageProps = {
+  src: string;
+  image?: ContentEntry["coverImage"];
+  alt: string;
+  className?: string;
+  /** How wide the image shows, for the browser to pick a size from srcset. */
+  sizes: string;
+  /** The first cover a reader sees: load it right away and early. Everything else waits until it is near. */
+  priority?: boolean;
+};
+
+/**
+ * A cover with resized WebP copies when the build made them. Width and height
+ * reserve the space, so nothing moves when the picture arrives.
+ */
+export function CoverImage({ src, image, alt, className, sizes, priority = false }: CoverImageProps) {
+  return (
+    // eslint-disable-next-line @next/next/no-img-element
+    <img
+      className={className}
+      src={image?.src ?? src}
+      srcSet={image?.srcset}
+      sizes={image ? sizes : undefined}
+      width={image?.width}
+      height={image?.height}
+      alt={alt}
+      loading={priority ? "eager" : "lazy"}
+      decoding="async"
+      fetchPriority={priority ? "high" : undefined}
+    />
+  );
+}

package/app/components/LinkCardRefresh.tsx

@@ -0,0 +1,44 @@
+"use client";
+
+import { useEffect } from "react";
+import { cardUpdates, fetchCardText, refreshUrl, safeToUpdate } from "../../ui/garden/card-refresh.mjs";
+
+/**
+ * After the page is idle, ask the link-card Worker for each card's current
+ * text and swap it in for cards below the fold. Any failure leaves the
+ * build-time card as it is.
+ */
+export function LinkCardRefresh({ endpoint }: { endpoint: string }) {
+  useEffect(() => {
+    const cards = [...document.querySelectorAll<HTMLElement>(".link-cards[data-card-url]")];
+    if (!cards.length || !refreshUrl(endpoint, "https://example.com/")) return;
+    // Aborts every request when the page goes away; each request also has its own timeout.
+    const controller = new AbortController();
+    const run = () => {
+      for (const card of cards) {
+        const target = refreshUrl(endpoint, card.dataset.cardUrl ?? "");
+        if (!target) continue;
+        fetchCardText(target, { shared: controller.signal })
+          .then((fresh) => {
+            if (!fresh || !safeToUpdate(card.getBoundingClientRect().top, window.innerHeight)) return;
+            const fields = new Map(
+              [...card.querySelectorAll<HTMLElement>("[data-field]")].map((node) => [node.dataset.field ?? "", node]),
+            );
+            const current = Object.fromEntries([...fields].map(([field, node]) => [field, node.textContent ?? ""]));
+            for (const [field, text] of Object.entries(cardUpdates(current, fresh))) {
+              const node = fields.get(field);
+              if (node) node.textContent = text;
+            }
+          })
+          .catch(() => {});
+      }
+    };
+    const idle = window.requestIdleCallback ?? ((callback: () => void) => window.setTimeout(callback, 1500));
+    const handle = idle(run);
+    return () => {
+      controller.abort();
+      (window.cancelIdleCallback ?? window.clearTimeout)(handle as number);
+    };
+  }, [endpoint]);
+  return null;
+}

package/app/components/MarkdownArticle.tsx

@@ -1,5 +1,6 @@
 import { markdownPlugins } from "../lib/markdown-plugins";
 import { remarkA2 } from "../lib/remark-a2.mjs";
+import { remarkLinkCard } from "../lib/remark-link-card.mjs";
 import {
   Children,
   cloneElement,
@@ -19,6 +20,42 @@ import { MarkdownImage } from "./MarkdownImage";
 import { CodeCopy } from "./garden/chrome";
 import { CodeDiff } from "./garden/chrome";
 import { GardenBlock } from "./garden/GardenBlock";
+import { linkAssets } from "@garden/generated-content";
+import { siteConfig } from "@garden/site-config";
+import { LinkCardRefresh } from "./LinkCardRefresh";
+import { linkHost } from "../../scripts/link-meta-core.mjs";
+import { cardDate } from "../../ui/garden/card-refresh.mjs";
+
+/** The site's favicon, downloaded at build time; nothing when there is none. */
+function Favicon({ href }: { href: string }) {
+  const src = linkAssets?.favicons?.[linkHost(href)];
+  if (!src) return null;
+  // eslint-disable-next-line @next/next/no-img-element -- a 14px local icon, no optimisation needed
+  return <img className="fav" src={src} alt="" width={14} height={14} loading="lazy" decoding="async" aria-hidden="true" />;
+}
+
+/** The first word of a link (or its first CJK character) and the rest. */
+const firstWord = (text: string) => {
+  const match = /^(\s*(?:[\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}\p{Script=Hangul}]|[^\s\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}\p{Script=Hangul}]+))([\s\S]*)$/u.exec(text);
+  return match ? [match[1], match[2]] : [text, ""];
+};
+
+/** Icon plus the link's first word on one line, so the icon never ends a line alone. */
+function WithFavicon({ href, children }: { href: string; children: ReactNode }) {
+  const icon = <Favicon href={href} />;
+  if (!linkAssets?.favicons?.[linkHost(href)]) return <>{children}</>;
+  const nodes = Children.toArray(children);
+  const head = nodes[0];
+  if (typeof head !== "string") return <><span className="fav-keep">{icon}</span>{children}</>;
+  const [first, rest] = firstWord(head);
+  return (
+    <>
+      <span className="fav-keep">{icon}{first}</span>
+      {rest}
+      {nodes.slice(1)}
+    </>
+  );
+}
 
 const BLOCK_LANGUAGES = ["language-mermaid"];
 const isBlockLanguage = (className?: string) =>
@@ -76,24 +113,43 @@ function stripPrefix(children: ReactNode, prefix: string): ReactNode {
   return walk(children);
 }
 
-function LinkCard({ href }: { href: string }) {
-  let host = href;
-  try { host = new URL(href).hostname.replace(/^www\./u, ""); } catch { /* keep the raw url */ }
+
+/**
+ * A link card. Standalone (the author's paragraph was just the link), it is the
+ * link. After a paragraph that keeps the link, it is a preview: out of the tab
+ * order and hidden from screen readers, since the link is already there.
+ */
+export function LinkCard({ href, text, standalone = true }: { href: string; text?: string; standalone?: boolean }) {
+  const meta = linkAssets?.cards?.[href];
+  const host = linkHost(href) || href;
+  const icon = linkAssets?.favicons?.[host];
+  const title = meta?.title || text || href;
+  const date = cardDate(meta?.publishedTime);
+  const preview = standalone ? {} : { tabIndex: -1, "aria-hidden": true as const };
   return (
-    <ul className="link-cards">
-      <li>
-        <a className="link-card ext" href={href} target="_blank" rel="noopener noreferrer">
-          <span className="lc-body">
-            <span className="lc-site">
-              <span className="lc-sitename">{host}</span>
-              <span className="lc-host">{host}</span>
-              <span className="lc-arrow" aria-hidden="true" />
-            </span>
-            <span className="lc-title">{href}</span>
+    <div className="link-cards" data-card-url={href}>
+      <a className="link-card" href={href} target="_blank" rel="noopener noreferrer" {...preview}>
+        <span className="lc-body">
+          <span className="lc-site">
+            {/* eslint-disable-next-line @next/next/no-img-element -- local 14px icon */}
+            {icon ? <img className="fav" src={icon} alt="" width={14} height={14} loading="lazy" decoding="async" /> : null}
+            <span className="lc-sitename" data-field="siteName">{meta?.siteName || host}</span>
+            {meta?.siteName && meta.siteName.toLowerCase() !== host ? <span className="lc-host">{host}</span> : null}
+            <span className="lc-arrow" aria-hidden="true" />
           </span>
-        </a>
-      </li>
-    </ul>
+          <span className="lc-title" data-field="title">{title}</span>
+          {meta?.description ? <span className="lc-desc" data-field="description">{meta.description}</span> : null}
+          {meta?.author || date ? (
+            <span className="lc-meta">
+              {meta?.author ? <span data-field="author">{meta.author}</span> : null}
+              {date ? <time data-field="publishedTime" dateTime={meta?.publishedTime}>{date}</time> : null}
+            </span>
+          ) : null}
+        </span>
+        {/* eslint-disable-next-line @next/next/no-img-element -- copied into the site at build time */}
+        {meta?.image ? <img className="lc-thumb" src={meta.image} alt="" width={168} height={88} loading="lazy" decoding="async" /> : null}
+      </a>
+    </div>
   );
 }
 
@@ -109,6 +165,8 @@ const headingText = (children: ReactNode) => {
 };
 
 export function MarkdownArticle({ content }: { content: string }) {
+  // 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 headingBase = articleHeadingBase(content);
@@ -136,6 +194,13 @@ export function MarkdownArticle({ content }: { content: string }) {
     return <Tag {...domProps}>{sectioned.no ? <span className="sec-no">{sectioned.no}</span> : null}{sectioned.children}</Tag>;
   };
   const gardenComponents = {
+    "garden-linkcard": (props: Record<string, string | undefined>) => (
+      <LinkCard
+        href={props.dataUrl ?? props["data-url"] ?? ""}
+        text={props.dataText ?? props["data-text"]}
+        standalone={(props.dataStandalone ?? props["data-standalone"]) === "true"}
+      />
+    ),
     "garden-block": (props: { dataPayload?: string; "data-payload"?: string }) => (
       <GardenBlock dataPayload={props.dataPayload ?? props["data-payload"]} />
     ),
@@ -156,7 +221,7 @@ export function MarkdownArticle({ content }: { content: string }) {
   return (
     <div className="markdown-body prose">
       <ReactMarkdown
-        remarkPlugins={[...markdownPlugins, remarkA2]}
+        remarkPlugins={[...markdownPlugins, remarkLinkCard, remarkA2]}
         rehypePlugins={[
           rehypeRaw,
           rehypeKatex,
@@ -177,15 +242,17 @@ export function MarkdownArticle({ content }: { content: string }) {
           },
           a: ({ href, children, ...props }) => {
             const external = Boolean(href && /^(https?:)?\/\//iu.test(href));
+            const domProps = { ...props };
+            Reflect.deleteProperty(domProps, "node");
             return (
               <a
                 href={href}
-                {...props}
+                {...domProps}
                 {...(external
                   ? { className: "ext", target: "_blank", rel: "noopener noreferrer" }
                   : {})}
               >
-                {children}
+                {external && href ? <WithFavicon href={href}>{children}</WithFavicon> : children}
               </a>
             );
           },
@@ -225,6 +292,7 @@ export function MarkdownArticle({ content }: { content: string }) {
       >
         {content}
       </ReactMarkdown>
+      {cardWorker ? <LinkCardRefresh endpoint={cardWorker} /> : null}
     </div>
   );
 }