hd-garden 0.8.4 → 0.9.1

package/app/components/bookshelf/catalog.mjs

@@ -0,0 +1,116 @@
+import { marked } from "marked";
+import { BookshelfConfigError } from "./schema.mjs";
+
+/**
+ * Site shelf for `<Bookshelf catalog notes />`.
+ * Built only from `content/bookshelf.yaml` and the posts it names.
+ * The package demo is a separate path: this module never reads it.
+ *
+ * `post` is a `content/posts` path without `.md`. Its front matter description
+ * leads the note HTML so the open book's right page is that summary.
+ * A cover file name is published at `/media/covers/<file>` (same stem cleanup
+ * as content sync). A full URL or a path starting with `/` is kept.
+ */
+
+const WIDGET_FENCE = /```(?:garden|ui-error|ui|intent|widget)(?:[ \t]+[^\n]*)?\r?\n[\s\S]*?```/gu;
+
+export function resolveBookshelfCover(cover, where = "cover") {
+  if (!cover?.trim()) return undefined;
+  const value = cover.trim();
+  if (/^(?:[a-z][a-z0-9+.-]*:)?\/\//iu.test(value) || value.startsWith("/") || value.startsWith("data:")) {
+    return value;
+  }
+  let relative = value.replace(/^\.\//u, "");
+  if (relative.startsWith("covers/")) relative = relative.slice("covers/".length);
+  const parts = relative.split("/");
+  if (!relative || parts.some((segment) => segment === "" || segment === "." || segment === "..")) {
+    throw new BookshelfConfigError("cover", `${where} 的 cover 必须是文件名或完整 URL。`);
+  }
+  return `/media/covers/${parts.map(publishCoverSegment).join("/")}`;
+}
+
+/** `content/posts` path, without `.md`. Rejects anything that leaves that directory. */
+export function normalizeBookshelfPostPath(value) {
+  const relative = value
+    .trim()
+    .replaceAll("\\", "/")
+    .replace(/^(?:content\/)?posts\//u, "")
+    .replace(/\.md$/u, "");
+  if (
+    !relative
+    || relative.startsWith("/")
+    || relative.split("/").some((segment) => segment === "" || segment === "." || segment === "..")
+  ) {
+    throw new BookshelfConfigError("post", `post「${value}」必须是 content/posts 下的路径，不带 .md。`);
+  }
+  return relative;
+}
+
+export function bookshelfMountFromFile(file, posts) {
+  const byPath = new Map(posts.map((post) => [normalizeBookshelfPostPath(post.path), post]));
+  const notes = {};
+  const catalog = file.shelves.map((shelf) => ({
+    id: shelf.id,
+    name: shelf.name,
+    books: shelf.books.map((book) => toCatalogBook(book, byPath, notes)),
+  }));
+  return {
+    title: file.title,
+    description: file.description,
+    eyebrow: file.eyebrow,
+    catalog,
+    notes,
+  };
+}
+
+function toCatalogBook(book, byPath, notes) {
+  const post = book.post ? byPath.get(normalizeBookshelfPostPath(book.post)) : undefined;
+  if (book.post && !post) {
+    throw new BookshelfConfigError("post", `书架引用的博文 ${book.post} 没有读到。`);
+  }
+  const cover = resolveBookshelfCover(book.cover, book.id) ?? (post ? resolveBookshelfCover(post.cover, book.id) : undefined);
+  const body = post
+    ? renderNoteHtml(post.content, post.description)
+    : book.note
+      ? renderNoteHtml(book.note)
+      : "";
+  const note = body ? book.id : null;
+  if (note) notes[book.id] = { title: book.title, body, summary: post?.description };
+  return {
+    id: book.id,
+    title: book.title,
+    author: book.author ?? "",
+    spine: book.spine ?? book.title,
+    size: book.size ?? (book.filler ? "thin" : "s-mid"),
+    cover: cover ?? false,
+    color: book.color,
+    filler: book.filler,
+    post: book.post ? normalizeBookshelfPostPath(book.post) : undefined,
+    note,
+  };
+}
+
+function renderNoteHtml(markdown, description) {
+  const prose = markdown.replace(WIDGET_FENCE, "\n").trim();
+  const parsed = prose ? marked.parse(prose, { async: false }).trim() : "";
+  const summary = description?.trim();
+  if (!summary || prose.includes(summary)) return parsed;
+  return `<p>${escapeHtml(summary)}</p>${parsed ? `\n${parsed}` : ""}`;
+}
+
+function publishCoverSegment(segment, index, all) {
+  const isFile = index === all.length - 1;
+  if (!isFile) return encodeURIComponent(segment.replace(/[^\w\u3400-\u9fff.-]+/gu, "-"));
+  const dot = segment.lastIndexOf(".");
+  const ext = dot >= 0 ? segment.slice(dot).toLowerCase() : "";
+  const stem = dot >= 0 ? segment.slice(0, dot) : segment;
+  return encodeURIComponent(`${stem.replace(/[^\w\u3400-\u9fff.-]+/gu, "-")}${ext}`);
+}
+
+function escapeHtml(value) {
+  return value
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;");
+}

package/app/components/bookshelf/catalog.ts

@@ -0,0 +1,23 @@
+import type { BookshelfNote, BookshelfShelf } from "./types";
+
+/**
+ * Site shelf ready for `<Bookshelf catalog notes />`.
+ * The runtime lives in `catalog.mjs` (node tests and the page share it).
+ * The package demo is not an input.
+ */
+export type BookshelfMount = {
+  title: string;
+  description?: string;
+  eyebrow?: string;
+  catalog: BookshelfShelf[];
+  notes: Record<string, BookshelfNote>;
+};
+
+/** A post the shelf can turn into a note. `path` is relative to `content/posts`, without `.md`. */
+export type BookshelfPostSource = {
+  path: string;
+  title?: string;
+  description?: string;
+  cover?: string;
+  content: string;
+};

package/app/components/bookshelf/demo-data.ts

@@ -0,0 +1,93 @@
+import type { BookshelfNote, BookshelfShelf } from "./types";
+
+export const DEMO_CATALOG: BookshelfShelf[] = [
+    {
+      id: "tools",
+      name: "工具与基础",
+      books: [
+        { id: "clean-code", title: "代码整洁之道", author: "Robert C. Martin", spine: "代码整洁之道", size: "s-tall", cover: true, note: "clean-code" },
+        { id: "refactoring", title: "重构", author: "Martin Fowler", spine: "重构", size: "s-mid", cover: true, note: null },
+        { id: "design-patterns", title: "设计模式", author: "GoF", spine: "设计模式", size: "s-tall", cover: true, note: null },
+        { id: "mythical-man-month", title: "人月神话", author: "Frederick Brooks", spine: "人月神话", size: "s-mid", cover: true, note: null },
+        { id: "zaji-1", title: "札记", author: "", spine: "札记", size: "thin", cover: false, filler: "sand", note: null },
+        { id: "biji-1", title: "笔记", author: "", spine: "笔记", size: "thin", cover: false, filler: "cream", note: null },
+      ],
+    },
+    {
+      id: "eng",
+      name: "工程实践",
+      books: [
+        { id: "continuous-delivery", title: "持续交付", author: "Jez Humble", spine: "持续交付", size: "s-tall", cover: true, note: null },
+        { id: "phoenix-project", title: "凤凰项目", author: "Gene Kim", spine: "凤凰项目", size: "s-mid", cover: true, note: null },
+        { id: "pragmatic-programmer", title: "程序员修炼之道", author: "David Thomas & Andrew Hunt", spine: "程序员修炼之道", size: "s-mid", cover: true, note: "pragmatic-programmer" },
+        { id: "tdd", title: "测试驱动开发", author: "Kent Beck", spine: "测试驱动开发", size: "s-tall", cover: true, note: null },
+        { id: "lean-startup", title: "精益创业", author: "Eric Ries", spine: "精益创业", size: "s-mid", cover: true, note: null },
+        { id: "release-it", title: "发布！", author: "Michael Nygard", spine: "发布！", size: "s-short", cover: true, note: null },
+        { id: "sre", title: "SRE 实践", author: "Google", spine: "SRE 实践", size: "s-mid", cover: true, note: null },
+        { id: "zaji-2", title: "札记", author: "", spine: "札记", size: "thin", cover: false, filler: "sand", note: null },
+        { id: "team-topologies", title: "团队拓扑", author: "Matthew Skelton", spine: "团队拓扑", size: "s-mid", cover: true, note: null },
+        { id: "accelerate", title: "加速", author: "Nicole Forsgren", spine: "加速", size: "s-tall", cover: true, note: null },
+      ],
+    },
+    {
+      id: "arch",
+      name: "领域与架构",
+      books: [
+        { id: "ddd", title: "领域驱动设计", author: "Eric Evans", spine: "领域驱动设计", size: "s-tall", cover: true, note: null },
+        { id: "microservices", title: "微服务设计", author: "Sam Newman", spine: "微服务设计", size: "s-mid", cover: true, note: null },
+        { id: "eaa", title: "企业应用架构模式", author: "Martin Fowler", spine: "企业应用架构模式", size: "s-mid", cover: true, note: null },
+        { id: "ddia", title: "数据密集型应用", author: "Martin Kleppmann", spine: "数据密集型应用", size: "s-tall", cover: true, note: "ddia" },
+        { id: "fundamentals-sa", title: "软件架构基础", author: "Mark Richards", spine: "软件架构基础", size: "s-short", cover: true, note: null },
+        { id: "implementing-ddd", title: "实现领域驱动设计", author: "Vaughn Vernon", spine: "实现领域驱动设计", size: "s-mid", cover: true, note: null },
+        { id: "biji-2", title: "笔记", author: "", spine: "笔记", size: "thin", cover: false, filler: "cream", note: null },
+        { id: "systems-performance", title: "性能之巅", author: "Brendan Gregg", spine: "性能之巅", size: "s-mid", cover: true, note: null },
+        { id: "clean-architecture", title: "架构整洁之道", author: "Robert C. Martin", spine: "架构整洁之道", size: "s-tall", cover: true, note: null },
+      ],
+    },
+  ];
+
+export const DEMO_NOTES: Record<string, BookshelfNote> = {
+    "pragmatic-programmer": {
+      title: "程序员修炼之道",
+      body: `
+        <h2>为什么还在读这本</h2>
+        <p>不是为了清单打卡，是为了把「匠人感」拉回日常：小步验证、可逆决定、别把偶然当设计。</p>
+        <h2>几条带走的</h2>
+        <ul>
+          <li>DRY 不是少敲几行字，是别让同一条知识活在两处。</li>
+          <li>正交：改一处不该惊动无关处。</li>
+          <li>抛出异常要够具体，吞掉异常等于撒谎。</li>
+        </ul>
+        <p>合上后仍会问自己：今天写的代码，半年后的我还认得出意图吗？</p>
+      `,
+    },
+    "clean-code": {
+      title: "代码整洁之道",
+      body: `
+        <h2>整洁不是洁癖</h2>
+        <p>可读性是团队带宽。命名、函数长度、副作用边界，比任何风格指南都更直接决定协作成本。</p>
+        <h2>记下的几条</h2>
+        <ul>
+          <li>函数做一件事，并且把它做完。</li>
+          <li>注释解释「为什么」，别复述「做了什么」。</li>
+          <li>坏味道先闻到，再谈重构顺序。</li>
+        </ul>
+        <p>Demo 笔记：正式站会换成完整读书笔记正文。</p>
+      `,
+    },
+    ddia: {
+      title: "数据密集型应用系统设计",
+      body: `
+        <h2>为什么这本难跳过</h2>
+        <p>把复制、分区、事务、流处理放进同一张地图里。读完后「CAP」不再是面试口号，而是取舍清单。</p>
+        <h2>带走的框架</h2>
+        <ul>
+          <li>可靠性 / 可扩展性 / 可维护性：先问系统要哪一项。</li>
+          <li>写放大与读放大：每加一层缓存都要付账。</li>
+          <li>一致性不是开关，是光谱。</li>
+        </ul>
+        <p>合上书，仍会用它的词汇表去审自己的服务边界。</p>
+      `,
+    },
+  };
+

package/app/components/bookshelf/density.ts

@@ -0,0 +1,32 @@
+import type { BookshelfShelf } from "./types";
+
+export const MID_W = 132;
+export const MID_H = 198;
+
+/** Places `fromRect` onto `toRect`. `extra` is the demo's rotateZ term. */
+export function flipTransform(
+  fromRect: { left: number; top: number; width: number; height: number },
+  toRect: { left: number; top: number; width: number; height: number },
+  extra = "",
+): string {
+  const sx = fromRect.width / toRect.width;
+  const sy = fromRect.height / toRect.height;
+  const tx = fromRect.left - toRect.left;
+  const ty = fromRect.top - toRect.top;
+  return `translate(${tx}px, ${ty}px) scale(${sx}, ${sy})${extra ? " " + extra : ""}`;
+}
+
+/**
+ * Page-level density from the approved demo.
+ * If any row's covers cannot fit the text column, every row is spines.
+ */
+export function pageDensity(catalog: readonly Pick<BookshelfShelf, "books">[], viewportWidth: number): "covers" | "spines" {
+  const col = Math.min(viewportWidth - 32, 740);
+  const coverW = viewportWidth <= 640 ? 102 + 10 : 118 + 14;
+  for (const cat of catalog) {
+    const n = cat.books.filter((b) => b.cover).length;
+    const need = n * coverW;
+    if (need > col - 8) return "spines";
+  }
+  return "covers";
+}