for-humanity 0.2.1 → 0.4.0

package/dist/cli.js

@@ -2,9 +2,9 @@
 
 // src/cli.ts
 import { EventEmitter } from "node:events";
-import { existsSync as existsSync2, watch } from "node:fs";
+import { existsSync as existsSync3, watch } from "node:fs";
 import { copyFile, mkdir, rm, writeFile } from "node:fs/promises";
-import { basename as basename2, dirname as dirname3, join as join4, relative as relative3, resolve as resolve2 } from "node:path";
+import { basename as basename2, dirname as dirname4, extname as extname4, join as join4, relative as relative4, resolve as resolve3, sep as sep3 } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { serve } from "@hono/node-server";
 import { serveStatic } from "@hono/node-server/serve-static";
@@ -73,8 +73,12 @@ import clsx2 from "clsx";
 import { Fragment } from "react";
 import { jsx as jsx2, jsxs as jsxs2 } from "react/jsx-runtime";
 var WgShellNavList = (props) => {
+  const currentAncestors = new Set(props.currentDoc?.ancestors);
   const entries = [
-    ...props.group.docs.map((doc) => ({ kind: "document", key: `doc:${doc.id}`, doc, current: doc.id === props.currentDoc?.id })),
+    ...props.group.docs.map((doc) => {
+      const active = doc.id === props.currentDoc?.id;
+      return { kind: "document", key: `doc:${doc.id}`, doc, active, current: active || currentAncestors.has(doc.id) };
+    }),
     ...props.group.groups.map((group) => ({
       kind: "group",
       key: `group:${JSON.stringify(group.path)}`,
@@ -91,16 +95,25 @@ var WgShellNavList = (props) => {
         "wg_shellNavList__item--current": entry.current
       }),
       children: [
-        entry.kind === "document" && /* @__PURE__ */ jsx2(
-          "a",
-          {
-            className: clsx2("wg_shellNavList__link", { "wg_shellNavList__link--active": entry.current }),
-            href: `/${entry.doc.id}/`,
-            title: entry.doc.data.label,
-            "aria-current": entry.current ? "page" : void 0,
-            children: entry.doc.data.name
-          }
-        ),
+        entry.kind === "document" && /* @__PURE__ */ jsxs2(Fragment, { children: [
+          /* @__PURE__ */ jsx2(
+            "a",
+            {
+              className: clsx2("wg_shellNavList__link", { "wg_shellNavList__link--active": entry.active }),
+              href: `/${entry.doc.id}/`,
+              title: entry.doc.data.label,
+              "aria-current": entry.active ? "page" : void 0,
+              children: entry.doc.data.name
+            }
+          ),
+          entry.doc.children !== void 0 && /* @__PURE__ */ jsx2(
+            WgShellNavList,
+            {
+              group: { name: entry.doc.data.name, path: entry.doc.data.group, docs: entry.doc.children, groups: [] },
+              currentDoc: props.currentDoc
+            }
+          )
+        ] }),
         entry.kind === "group" && /* @__PURE__ */ jsxs2(Fragment, { children: [
           /* @__PURE__ */ jsx2("span", { className: clsx2("wg_shellNavList__branch"), children: entry.group.name }),
           /* @__PURE__ */ jsx2(WgShellNavList, { group: entry.group, currentDoc: props.currentDoc })
@@ -118,7 +131,7 @@ var copy_nav_open = "Open navigation";
 var copy_nav_close = "Close navigation";
 var copy_nav_title = "Navigation";
 var copy_home_missing = "\uBB38\uC11C \uD3F4\uB354\uC5D0 README.md\uB97C \uCD94\uAC00\uD558\uBA74 \uC774\uACF3\uC5D0 \uD648 \uD654\uBA74\uC73C\uB85C \uD45C\uC2DC\uB429\uB2C8\uB2E4.";
-var copy_nav_toc_label = "Contents";
+var copy_nav_toc_label = "On this page";
 var copy_error_home_clash = "\uD648 README\uAC00 \uACB9\uCE5C\uB2E4";
 var copy_error_prefix = "for-humanity";
 var copy_error_font_preload = "Missing bundled font for preload";
@@ -128,16 +141,28 @@ var copy_error_frontmatter = "frontmatter\uAC00 \uC62C\uBC14\uB974\uC9C0 \uC54A\
 var copy_error_navigation_clash = "navigation\uC758 \uBB36\uC74C\uC774 \uACB9\uCE5C\uB2E4";
 var copy_error_doc_id = "\uBB38\uC11C id\uC5D0 \uC0AC\uC6A9\uD560 \uC218 \uC5C6\uB294 \uACBD\uB85C";
 var copy_error_doc_id_clash = "\uBB38\uC11C id\uAC00 \uACB9\uCE5C\uB2E4";
+var copy_error_doc_parent_missing = "\uBD80\uBAA8 \uBB38\uC11C\uAC00 \uC5C6\uB2E4";
+var copy_error_doc_parent_cycle = "\uBB38\uC11C parent\uAC00 \uC21C\uD658\uD55C\uB2E4";
+var copy_error_doc_parent_group = "\uBD80\uBAA8 \uBB38\uC11C\uC640 group\uC774 \uB2E4\uB974\uB2E4";
 var copy_error_flow = "\uD750\uB984\uB3C4\uB97C \uADF8\uB9AC\uC9C0 \uBABB\uD588\uB2E4";
 var copy_error_unknown_directive = "\uBAA8\uB974\uB294 \uBD80\uD488\uC774\uB2E4";
 var copy_error_directive_syntax = "\uBD80\uD488 \uBB38\uBC95\uC774 \uC62C\uBC14\uB974\uC9C0 \uC54A\uB2E4";
 var copy_warn_broken_link = "\uC5C6\uB294 \uBB38\uC11C\uB85C \uAC74 \uB9C1\uD06C\uB2E4";
 var copy_warn_unknown_status = "\uC124\uC815\uC5D0 \uC5C6\uB294 \uC0C1\uD0DC \uBB38\uAD6C\uB2E4";
+var copy_error_asset = "\uC790\uC6D0\uC774 \uC62C\uBC14\uB974\uC9C0 \uC54A\uB2E4";
 
 // src/constant/locale.ts
 var locale_doc_name = "en";
 var locale_doc_group = "ko";
 
+// src/content/to-doc-groups/_to-doc-branches.ts
+var toDocBranches = (options) => {
+  return options.docs.toSorted((a, b) => a.data.order - b.data.order || a.data.name.localeCompare(b.data.name, locale_doc_name) || a.id.localeCompare(b.id, locale_doc_name)).map((doc) => {
+    const children = options.children.get(doc.id);
+    return { ...doc, children: children === void 0 ? void 0 : toDocBranches({ docs: children, children: options.children }) };
+  });
+};
+
 // src/content/to-doc-groups/_to-doc-group-branches.ts
 var toDocGroupBranches = (options) => {
   return [
@@ -157,8 +182,17 @@ var toDocGroupBranches = (options) => {
     return {
       name: group.name,
       path: group.path,
-      docs: group.docs.filter((doc) => doc.data.group.length === group.path.length).toSorted((a, b) => a.data.order - b.data.order || a.data.name.localeCompare(b.data.name, locale_doc_name) || a.id.localeCompare(b.id, locale_doc_name)),
-      groups: toDocGroupBranches({ docs: group.docs, path: group.path, positions: options.positions, unlistedPosition: options.unlistedPosition })
+      docs: toDocBranches({
+        docs: group.docs.filter((doc) => doc.data.group.length === group.path.length && doc.data.parent === void 0),
+        children: options.children
+      }),
+      groups: toDocGroupBranches({
+        docs: group.docs,
+        children: options.children,
+        path: group.path,
+        positions: options.positions,
+        unlistedPosition: options.unlistedPosition
+      })
     };
   });
 };
@@ -166,7 +200,8 @@ var toDocGroupBranches = (options) => {
 // src/content/to-doc-groups/to-doc-groups.ts
 var toDocGroups = (options) => {
   const positions = new Map(options.navigation.flatMap((path, index) => path.map((_name, depth) => [JSON.stringify(path.slice(0, depth + 1)), index])).toReversed());
-  return toDocGroupBranches({ docs: options.docs, path: [], positions, unlistedPosition: options.navigation.length });
+  const children = Map.groupBy(options.docs, (doc) => doc.data.parent);
+  return toDocGroupBranches({ docs: options.docs, children, path: [], positions, unlistedPosition: options.navigation.length });
 };
 
 // src/component/widget/shell/_wg-shell-nav.tsx
@@ -208,9 +243,21 @@ var asset_content_types = {
   ".css": "text/css; charset=utf-8",
   ".js": "text/javascript; charset=utf-8",
   ".woff2": "font/woff2",
-  ".svg": "image/svg+xml"
+  ".svg": "image/svg+xml",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".webp": "image/webp",
+  ".avif": "image/avif",
+  ".pdf": "application/pdf",
+  ".csv": "text/csv; charset=utf-8",
+  ".txt": "text/plain; charset=utf-8",
+  ".zip": "application/zip"
 };
 var asset_content_type_default = "application/octet-stream";
+var asset_media_dir = `/${asset_dir}/media`;
+var asset_media_extensions = /* @__PURE__ */ new Set([".svg", ".png", ".jpg", ".jpeg", ".gif", ".webp", ".avif", ".pdf", ".csv", ".txt", ".zip"]);
 
 // src/component/widget/shell/wg-shell.tsx
 import { jsx as jsx5, jsxs as jsxs5 } from "react/jsx-runtime";
@@ -934,14 +981,67 @@ var remarkUnknownDirectives = () => (tree, file) => {
   });
 };
 
+// src/content/rehype-assets.ts
+import { existsSync as existsSync2, realpathSync, statSync } from "node:fs";
+import { dirname as dirname2, extname, isAbsolute, relative as relative2, resolve as resolve2, sep } from "node:path";
+import { visit as visit7 } from "unist-util-visit";
+
+// src/util/file/to-asset-path.ts
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { posix as posix2 } from "node:path";
+var toAssetPath = (options) => {
+  const extension = posix2.extname(options.path);
+  return `${posix2.dirname(options.path)}/${posix2.basename(options.path, extension)}.${createHash("sha256").update(readFileSync(options.file)).digest("hex")}${extension}`;
+};
+
+// src/content/rehype-assets.ts
+var rehypeAssets = (options) => (tree, file) => {
+  visit7(tree, "element", (node) => {
+    const property = node.tagName === "img" ? "src" : "href";
+    const url = node.properties[property];
+    if (node.tagName !== "img" && node.tagName !== "a" || typeof url !== "string" || /^(?:[a-z][a-z\d+.-]*:|\/|#)/i.test(url)) {
+      return;
+    }
+    const match = /^([^?#]+)([?#].*)?$/.exec(url);
+    if (match === null) {
+      return;
+    }
+    const path = decodeURIComponent(match[1]);
+    const extension = extname(path).toLowerCase();
+    if (!asset_media_extensions.has(extension)) {
+      if (node.tagName === "img") {
+        file.fail(`${copy_error_asset}: \uC9C0\uC6D0\uD558\uC9C0 \uC54A\uB294 \uC774\uBBF8\uC9C0 \uD615\uC2DD \xB7 ${url}`, node);
+      }
+      return;
+    }
+    const target = resolve2(dirname2(file.path), path);
+    const location = relative2(options.root, target);
+    if (location === ".." || location.startsWith(`..${sep}`) || isAbsolute(location)) {
+      file.fail(`${copy_error_asset}: \uBB38\uC11C \uD3F4\uB354 \uBC16 \xB7 ${url}`, node);
+    }
+    if (!existsSync2(target)) {
+      file.fail(`${copy_error_asset}: \uD30C\uC77C\uC774 \uC5C6\uB2E4 \xB7 ${url}`, node);
+    }
+    const actual = realpathSync(target);
+    const actualLocation = relative2(realpathSync(options.root), actual);
+    if (actualLocation === ".." || actualLocation.startsWith(`..${sep}`) || isAbsolute(actualLocation) || !statSync(actual).isFile()) {
+      file.fail(`${copy_error_asset}: \uBB38\uC11C \uD3F4\uB354 \uBC16\uC774\uAC70\uB098 \uC77C\uBC18 \uD30C\uC77C\uC774 \uC544\uB2C8\uB2E4 \xB7 ${url}`, node);
+    }
+    const assetUrl = toAssetPath({ path: `${asset_media_dir}/asset${extension}`, file: actual });
+    options.files.set(assetUrl, actual);
+    node.properties[property] = match[2] === void 0 ? assetUrl : `${assetUrl}${match[2]}`;
+  });
+};
+
 // src/content/rehype-heading-ids.ts
 import Slugger from "github-slugger";
 import { toString as toPlainText3 } from "hast-util-to-string";
-import { visit as visit7 } from "unist-util-visit";
+import { visit as visit8 } from "unist-util-visit";
 var rehypeHeadingIds = () => (tree, file) => {
   const slugger = new Slugger();
   const headings = [];
-  visit7(tree, "element", (node) => {
+  visit8(tree, "element", (node) => {
     const depth = /^h([1-6])$/.exec(node.tagName)?.[1];
     if (depth === void 0) {
       return;
@@ -957,9 +1057,9 @@ var rehypeHeadingIds = () => (tree, file) => {
 };
 
 // src/content/remark-report.ts
-import { relative as relative2 } from "node:path";
+import { relative as relative3 } from "node:path";
 var remarkReport = (options) => (_tree, file) => {
-  const path = relative2(options.root, file.path);
+  const path = relative3(options.root, file.path);
   for (const message of file.messages) {
     console.warn(`${message.line === void 0 ? path : `${path}:${message.line}`} ${message.reason}`);
   }
@@ -967,12 +1067,12 @@ var remarkReport = (options) => (_tree, file) => {
 
 // src/content/create-processor.ts
 var createProcessor = (options) => {
-  return unified().use(remarkParse).use(remarkFrontmatter, ["yaml"]).use(remarkGfm).use(remarkSmartypants).use(remarkDirective).use(remarkBlocks).use(remarkParts).use(remarkFlow).use(remarkStatus, { status: options.site.status }).use(remarkSwatch).use(remarkLinks, { root: options.root }).use(remarkUnknownDirectives).use(remarkReport, { root: options.root }).use(remarkRehype, { allowDangerousHtml: true }).use(rehypeShiki, { theme: createCssVariablesTheme({ name: "for-humanity", variablePrefix: "--app-code-" }) }).use(rehypeHead).use(rehypeHeadingIds).use(rehypeSections).use(rehypeTables).use(rehypeRaw).use(rehypeStringify, { allowDangerousHtml: true });
+  return unified().use(remarkParse).use(remarkFrontmatter, ["yaml"]).use(remarkGfm).use(remarkSmartypants).use(remarkDirective).use(remarkBlocks).use(remarkParts).use(remarkFlow).use(remarkStatus, { status: options.site.status }).use(remarkSwatch).use(remarkLinks, { root: options.root }).use(remarkUnknownDirectives).use(remarkReport, { root: options.root }).use(remarkRehype, { allowDangerousHtml: true }).use(rehypeShiki, { theme: createCssVariablesTheme({ name: "for-humanity", variablePrefix: "--app-code-" }) }).use(rehypeHead).use(rehypeHeadingIds).use(rehypeSections).use(rehypeTables).use(rehypeRaw).use(rehypeAssets, { root: options.root, files: options.files ?? /* @__PURE__ */ new Map() }).use(rehypeStringify, { allowDangerousHtml: true });
 };
 
 // src/content/read-docs.ts
 import { readdir, readFile } from "node:fs/promises";
-import { join, sep } from "node:path";
+import { join, posix as posix3, sep as sep2 } from "node:path";
 import { VFile } from "vfile";
 import { parse as parseYaml } from "yaml";
 
@@ -1001,13 +1101,17 @@ var docDataSchema = z2.object({
    */
   label: z2.string(),
   /**
-   * 문서 종류 · blueprint 전용 표현 미구현
+   * 기존 type 값 호환 · 생략 권장, 렌더링 차이 없음
    */
   type: z2.enum(doc_type).default(doc_type.document),
   /**
    * 사이드바의 문서 묶음 경로 · 문자열도 배열로 정규화
    */
   group: groupPathSchema,
+  /**
+   * 같은 묶음 안의 부모 문서 id · 확장자 제외, ./·../ 상대 경로도 허용
+   */
+  parent: z2.string().trim().min(1).optional(),
   /**
    * 묶음 안의 읽는 순서 · 미지정 문서는 뒤에서 이름순
    */
@@ -1017,11 +1121,11 @@ var docDataSchema = z2.object({
 // src/content/read-docs.ts
 var readDocs = async (options) => {
   const paths = (await readdir(options.root, { recursive: true })).filter(
-    (path) => /\.mdx?$/i.test(path) && !/^(readme|agents|claude)\.md$/i.test(path) && !path.split(sep).includes("node_modules") && !path.startsWith(`dist${sep}`)
+    (path) => /\.mdx?$/i.test(path) && !/^(readme|agents|claude)\.md$/i.test(path) && !path.split(sep2).includes("node_modules") && !path.startsWith(`dist${sep2}`)
   );
   const docs = await Promise.all(
     paths.map(async (path) => {
-      const id = path.replace(/\.mdx?$/i, "").split(sep).join("/").toLowerCase();
+      const id = path.replace(/\.mdx?$/i, "").split(sep2).join("/").toLowerCase();
       const segments = id.split("/");
       if (segments.some((segment) => segment === "" || segment === "." || segment === ".." || segment === "index.html") || /[#?%*:\\]/.test(id) || /[\p{Cc}]/u.test(id) || segments[0] === asset_dir || segments[0] === asset_favicon_path.slice(1)) {
         throw new Error(`${copy_error_doc_id}: ${path}`);
@@ -1034,13 +1138,18 @@ var readDocs = async (options) => {
       if (!parsed.success) {
         throw new Error(`${copy_error_frontmatter}: ${path}: ${parsed.error.issues.map((issue) => `${issue.path.join(".")} ${issue.message}`).join(", ")}`);
       }
-      const fh = { frontmatter: parsed.data, headings: [], sections: [] };
+      const data = {
+        ...parsed.data,
+        parent: parsed.data.parent !== void 0 && /^\.\.?\//.test(parsed.data.parent) ? posix3.join(posix3.dirname(id), parsed.data.parent) : parsed.data.parent
+      };
+      const fh = { frontmatter: data, headings: [], sections: [] };
       file.data.fh = fh;
       tree.children = tree.children.filter((node) => node.type !== "yaml");
       const rendered = await options.processor.run(tree, file);
       return {
         id,
-        data: parsed.data,
+        data,
+        ancestors: [],
         html: options.processor.stringify(rendered, file),
         outline: { headings: fh.headings, sections: fh.sections }
       };
@@ -1050,7 +1159,25 @@ var readDocs = async (options) => {
   if (duplicateIds.length > 0) {
     throw new Error(`${copy_error_doc_id_clash}: ${duplicateIds.map((entry) => entry[0]).join(", ")}`);
   }
-  return docs;
+  const docsById = new Map(docs.map((doc) => [doc.id, doc]));
+  return docs.map((doc) => {
+    const ancestors = /* @__PURE__ */ new Set([doc.id]);
+    for (let parentId = doc.data.parent; parentId !== void 0; ) {
+      const parent = docsById.get(parentId);
+      if (parent === void 0) {
+        throw new Error(`${copy_error_doc_parent_missing}: ${doc.id} \u2192 ${parentId}`);
+      }
+      if (ancestors.has(parent.id)) {
+        throw new Error(`${copy_error_doc_parent_cycle}: ${[...ancestors, parent.id].join(" \u2192 ")}`);
+      }
+      if (JSON.stringify(parent.data.group) !== JSON.stringify(doc.data.group)) {
+        throw new Error(`${copy_error_doc_parent_group}: ${doc.id} \u2192 ${parent.id}`);
+      }
+      ancestors.add(parent.id);
+      parentId = parent.data.parent;
+    }
+    return { ...doc, ancestors: [...ancestors].slice(1).toReversed() };
+  });
 };
 
 // src/content/read-home.ts
@@ -1074,7 +1201,7 @@ var readHome = async (options) => {
 
 // src/dev.ts
 import { readFile as readFile3 } from "node:fs/promises";
-import { extname } from "node:path";
+import { extname as extname2 } from "node:path";
 import { Hono as Hono2 } from "hono";
 import { streamSSE } from "hono/streaming";
 var createDevApp = (options) => {
@@ -1084,8 +1211,8 @@ var createDevApp = (options) => {
     if (file === void 0) {
       return c.notFound();
     }
-    c.header("content-type", asset_content_types[extname(file)] ?? asset_content_type_default);
-    if (extname(file) === ".woff2") {
+    c.header("content-type", asset_content_types[extname2(file).toLowerCase()] ?? asset_content_type_default);
+    if (extname2(file) === ".woff2") {
       c.header("Cache-Control", font_cache_control);
     }
     return c.body(await readFile3(file));
@@ -1169,25 +1296,16 @@ var toErrorMessage = (error) => {
   return error instanceof Error ? error.message : String(error);
 };
 
-// src/util/file/to-asset-path.ts
-import { createHash } from "node:crypto";
-import { readFileSync } from "node:fs";
-import { posix as posix2 } from "node:path";
-var toAssetPath = (options) => {
-  const extension = posix2.extname(options.path);
-  return `${posix2.dirname(options.path)}/${posix2.basename(options.path, extension)}.${createHash("sha256").update(readFileSync(options.file)).digest("hex")}${extension}`;
-};
-
 // src/util/font/to-font-css.ts
 import { createHash as createHash2 } from "node:crypto";
 import { readFileSync as readFileSync2 } from "node:fs";
-import { basename, dirname as dirname2, extname as extname2, join as join3 } from "node:path";
+import { basename, dirname as dirname3, extname as extname3, join as join3 } from "node:path";
 var toFontCss = (options) => {
   const files = /* @__PURE__ */ new Map();
   const css = [...readFileSync2(options.css, "utf8").matchAll(/@font-face\s*\{[^}]*\}/g)].map(
     (match) => match[0].replace(/font-display:\s*[^;]+;/g, `font-display: ${font_display_strategy};`).replace(/url\(([^)]+)\)/g, (_match, relativeUrl) => {
-      const file = join3(dirname2(options.css), relativeUrl);
-      const extension = extname2(file);
+      const file = join3(dirname3(options.css), relativeUrl);
+      const extension = extname3(file);
       const hash = createHash2("sha256").update(readFileSync2(file)).digest("hex").slice(0, font_hash_length);
       const url = `${options.fontDir}/${basename(file, extension)}.${hash}${extension}`;
       files.set(url, file);
@@ -1205,14 +1323,14 @@ var main = async () => {
     throw new Error(`${copy_error_unknown_command}: ${command} (${commands.join(", ")})`);
   }
   const kitRoot = fileURLToPath(new URL("../", import.meta.url));
-  const docsRoot = resolve2(docsDir);
+  const docsRoot = resolve3(docsDir);
   const outDir = join4(docsRoot, "dist");
   if (command === "preview") {
     const app2 = new Hono3();
     app2.use(
       "/*",
       serveStatic({
-        root: relative3(process.cwd(), outDir),
+        root: relative4(process.cwd(), outDir),
         onFound: (_path, c) => {
           if (c.req.path.startsWith(`${asset_font_dir}/`)) {
             c.header("Cache-Control", font_cache_control);
@@ -1224,7 +1342,7 @@ var main = async () => {
     return;
   }
   const configFile = join4(docsRoot, cli_config_file_name);
-  const parsedConfig = siteConfigSchema.safeParse(existsSync2(configFile) ? (await import(pathToFileURL(configFile).href)).default : site_config_absent);
+  const parsedConfig = siteConfigSchema.safeParse(existsSync3(configFile) ? (await import(pathToFileURL(configFile).href)).default : site_config_absent);
   if (!parsedConfig.success) {
     throw new Error(`${copy_error_config}: ${parsedConfig.error.issues.map((issue) => `${issue.path.join(".")} ${issue.message}`).join(", ")}`);
   }
@@ -1239,7 +1357,7 @@ var main = async () => {
   const fontCss = [sans.css, mono.css, brand.css].join("\n");
   const stylePath = toAssetPath({ path: asset_style_path, file: join4(kitRoot, "dist/cli.css") });
   const clientPath = toAssetPath({ path: asset_client_path, file: join4(kitRoot, "dist/client.js") });
-  const files = new Map([
+  const kitFiles = new Map([
     [stylePath, join4(kitRoot, "dist/cli.css")],
     [clientPath, join4(kitRoot, "dist/client.js")],
     [asset_favicon_path, join4(kitRoot, "src/asset/favicon.svg")],
@@ -1247,7 +1365,8 @@ var main = async () => {
     ...mono.files,
     ...brand.files
   ]);
-  const processor = createProcessor({ site: siteConfig, root: docsRoot });
+  const files = new Map(kitFiles);
+  const processor = createProcessor({ site: siteConfig, root: docsRoot, files });
   const [docs, home] = await Promise.all([readDocs({ root: docsRoot, processor }), readHome({ root: docsRoot, processor })]);
   const store = { docs, home };
   const app = createApp({
@@ -1262,25 +1381,34 @@ var main = async () => {
       throw result.error;
     }
     for (const [url, file] of files) {
-      await mkdir(dirname3(join4(outDir, url)), { recursive: true });
+      await mkdir(dirname4(join4(outDir, url)), { recursive: true });
       await copyFile(file, join4(outDir, url));
     }
-    console.log(`${result.files.length} pages, ${files.size} assets \u2192 ${relative3(process.cwd(), outDir)}`);
+    console.log(`${result.files.length} pages, ${files.size} assets \u2192 ${relative4(process.cwd(), outDir)}`);
     return;
   }
   const reload = new EventEmitter();
   let generation = 0;
   serve({ fetch: createDevApp({ pages: app, files, reload }).fetch, port: cli_dev_port }, (info) => console.log(`http://localhost:${info.port}/`));
   const handleDocsChange = async (_event, filename) => {
-    if (filename !== null && !/\.mdx?$/i.test(filename)) {
-      return;
+    if (filename !== null) {
+      const segments = filename.split(sep3);
+      if (segments.includes("dist") || segments.includes("node_modules") || !/\.mdx?$/i.test(filename) && !asset_media_extensions.has(extname4(filename).toLowerCase())) {
+        return;
+      }
     }
     const currentGeneration = ++generation;
     try {
-      const [docs2, home2] = await Promise.all([readDocs({ root: docsRoot, processor }), readHome({ root: docsRoot, processor })]);
+      const nextFiles = new Map(kitFiles);
+      const nextProcessor = createProcessor({ site: siteConfig, root: docsRoot, files: nextFiles });
+      const [docs2, home2] = await Promise.all([readDocs({ root: docsRoot, processor: nextProcessor }), readHome({ root: docsRoot, processor: nextProcessor })]);
       if (currentGeneration !== generation) {
         return;
       }
+      files.clear();
+      for (const entry of nextFiles) {
+        files.set(...entry);
+      }
       store.docs = docs2;
       store.home = home2;
       reload.emit("change");

package/dist/client.js

@@ -1,5 +1,5 @@
-var L="fh-cursor-face";var S="(width < 1024px)";var p=e=>{if(!e)return null;try{return document.getElementById(decodeURIComponent(e.slice(1)))}catch(t){if(t instanceof URIError)return null;throw t}};var m=e=>{let t=p(e);for(let n=t?.closest("details");n;n=n.parentElement?.closest("details"))n.open=!0;return t};var k=()=>{let e=document.querySelector("[data-navigation]"),t=document.querySelector("[data-navigation-drawer]"),n=document.querySelector("[data-navigation-content]"),r=document.querySelector("[data-navigation-open]"),u=document.querySelector("[data-navigation-close]"),d=e?.parentElement;if(!e||!t||!n||!r||!u||!d)return;let s=matchMedia(S),l=()=>{t.open||(document.body.classList.remove("wg_shell__root--drawerOpen"),r.setAttribute("aria-expanded","false"))},h=()=>{t.close(),l()},a=()=>{!s.matches||t.open||(t.showModal(),document.body.classList.add("wg_shell__root--drawerOpen"),r.setAttribute("aria-expanded","true"))},c=o=>{let i=t.getBoundingClientRect();o.target===t&&(o.clientX<i.left||o.clientX>i.right||o.clientY<i.top||o.clientY>i.bottom)&&h()},q=o=>{if(!t.open||o.defaultPrevented||o.button!==0||o.metaKey||o.ctrlKey||o.shiftKey||o.altKey||!(o.target instanceof Element))return;let i=o.target.closest("a[href]");if(!(!(i instanceof HTMLAnchorElement)||i.target!==""&&i.target!=="_self"||i.hasAttribute("download"))&&(h(),i.origin===location.origin&&i.pathname===location.pathname&&i.search===location.search&&i.hash)){let T=m(i.hash);T&&(T.tabIndex=-1,T.focus({preventScroll:!0}))}},H=()=>{let o=document.activeElement;if(s.matches){r.classList.add("wg_shell__menuToggle--visible"),n.append(e),o instanceof HTMLElement&&e.contains(o)&&r.focus({preventScroll:!0});return}h(),d.append(e),o instanceof HTMLElement&&e.contains(o)?o.focus({preventScroll:!0}):(o===r||o instanceof HTMLElement&&t.contains(o))&&d.querySelector(".wg_shell__brand")?.focus({preventScroll:!0}),r.classList.remove("wg_shell__menuToggle--visible")};r.addEventListener("click",a),u.addEventListener("click",h),t.addEventListener("close",l),t.addEventListener("click",c),e.addEventListener("click",q),s.addEventListener("change",H),H(),d.classList.add("wg_shell__sidebar--navigationReady")};k();var g=document.querySelector("[data-cursor-face]");if(g){let e=matchMedia("(hover: hover) and (pointer: fine) and (prefers-reduced-motion: no-preference)"),t={x:0,y:0,frame:0},n=()=>{cancelAnimationFrame(t.frame),t.frame=0,g.classList.remove("wg_shell__cursorFace--visible")},r=()=>{e.matches||n()},u=()=>{t.frame===0&&(t.frame=requestAnimationFrame(()=>{t.frame=0,g.style.transform=`translate3d(
+var L="fh-cursor-face";var k="(width < 1024px)";var p=e=>{if(!e)return null;try{return document.getElementById(decodeURIComponent(e.slice(1)))}catch(t){if(t instanceof URIError)return null;throw t}};var m=e=>{let t=p(e);for(let n=t?.closest("details");n;n=n.parentElement?.closest("details"))n.open=!0;return t};var S=()=>{let e=document.querySelector("[data-navigation]"),t=document.querySelector("[data-navigation-drawer]"),n=document.querySelector("[data-navigation-content]"),i=document.querySelector("[data-navigation-open]"),d=document.querySelector("[data-navigation-close]"),c=e?.parentElement;if(!e||!t||!n||!i||!d||!c)return;let l=matchMedia(k),a=()=>{t.open||(document.body.classList.remove("wg_shell__root--drawerOpen"),i.setAttribute("aria-expanded","false"))},u=()=>{t.close(),a()},h=()=>{!l.matches||t.open||(t.showModal(),document.body.classList.add("wg_shell__root--drawerOpen"),i.setAttribute("aria-expanded","true"))},r=o=>{let s=t.getBoundingClientRect();o.target===t&&(o.clientX<s.left||o.clientX>s.right||o.clientY<s.top||o.clientY>s.bottom)&&u()},q=o=>{if(!t.open||o.defaultPrevented||o.button!==0||o.metaKey||o.ctrlKey||o.shiftKey||o.altKey||!(o.target instanceof Element))return;let s=o.target.closest("a[href]");if(!(!(s instanceof HTMLAnchorElement)||s.target!==""&&s.target!=="_self"||s.hasAttribute("download"))&&(u(),s.origin===location.origin&&s.pathname===location.pathname&&s.search===location.search&&s.hash)){let T=m(s.hash);T&&(T.tabIndex=-1,T.focus({preventScroll:!0}))}},H=()=>{let o=document.activeElement;if(l.matches){i.classList.add("wg_shell__menuToggle--visible"),n.append(e),o instanceof HTMLElement&&e.contains(o)&&i.focus({preventScroll:!0});return}u(),c.append(e),o instanceof HTMLElement&&e.contains(o)?o.focus({preventScroll:!0}):(o===i||o instanceof HTMLElement&&t.contains(o))&&c.querySelector(".wg_shell__brand")?.focus({preventScroll:!0}),i.classList.remove("wg_shell__menuToggle--visible")};i.addEventListener("click",h),d.addEventListener("click",u),t.addEventListener("close",a),t.addEventListener("click",r),e.addEventListener("click",q),l.addEventListener("change",H),H(),c.classList.add("wg_shell__sidebar--navigationReady")};S();var g=document.querySelector("[data-cursor-face]");if(g){let e=matchMedia("(hover: hover) and (pointer: fine) and (prefers-reduced-motion: no-preference)"),t={x:0,y:0,frame:0},n=()=>{cancelAnimationFrame(t.frame),t.frame=0,g.classList.remove("wg_shell__cursorFace--visible")},i=()=>{e.matches||n()},d=()=>{t.frame===0&&(t.frame=requestAnimationFrame(()=>{t.frame=0,g.style.transform=`translate3d(
                 ${Math.max(0,Math.min(t.x+16,document.documentElement.clientWidth-g.width-16))}px,
                 ${Math.max(0,Math.min(t.y+16,document.documentElement.clientHeight-g.height-16))}px,
                 0
-            )`,g.classList.add("wg_shell__cursorFace--visible")}))},d=a=>{if(!(e.matches&&a.pointerType==="mouse")){n();return}t.x=a.clientX,t.y=a.clientY,u()},s=()=>{g.classList.contains("wg_shell__cursorFace--visible")&&u()},l=()=>{if(g.classList.contains("wg_shell__cursorFace--visible"))try{sessionStorage.setItem(L,JSON.stringify({x:t.x,y:t.y}))}catch{}},h=()=>{try{let a=sessionStorage.getItem(L);if(sessionStorage.removeItem(L),a!==null&&e.matches){let c=JSON.parse(a);typeof c=="object"&&c!==null&&"x"in c&&"y"in c&&typeof c.x=="number"&&typeof c.y=="number"&&Number.isFinite(c.x)&&Number.isFinite(c.y)&&(t.x=c.x,t.y=c.y,u())}}catch{}};h(),document.addEventListener("pointermove",d,{passive:!0}),document.addEventListener("pointerdown",d,{passive:!0}),document.documentElement.addEventListener("pointerleave",n),addEventListener("blur",n),addEventListener("resize",s),addEventListener("pagehide",l),addEventListener("pageshow",h),e.addEventListener("change",r)}var v=m(location.hash),_=null,b=0,f=null,x=()=>{clearTimeout(b),f?.abort(),f=null,_?.classList.remove("wg_prose__headingText--highlighted"),_=null},M=e=>{x(),_=e===null?null:e.querySelector(".wg_prose__headingText"),_!==null&&(_.classList.add("wg_prose__headingText--highlighted"),b=window.setTimeout(x,3e3),f=new AbortController,document.addEventListener("scrollend",B,{signal:f.signal}))},B=e=>{e.target===document&&(clearTimeout(b),f?.abort(),f=null,b=window.setTimeout(x,3e3))},N=e=>{if(!(e.defaultPrevented||e.button!==0||e.metaKey||e.ctrlKey||e.shiftKey||e.altKey)&&e.currentTarget instanceof HTMLAnchorElement&&(e.currentTarget.target===""||e.currentTarget.target==="_self")&&!e.currentTarget.hasAttribute("download")&&e.currentTarget.origin===location.origin&&e.currentTarget.pathname===location.pathname&&e.currentTarget.search===location.search&&e.currentTarget.hash){let t=m(e.currentTarget.hash);e.currentTarget.hash===location.hash&&M(t)}},K=()=>{let e=m(location.hash);e?.scrollIntoView(),M(e)};for(let e of document.querySelectorAll("a[href]"))e.addEventListener("click",N);addEventListener("hashchange",K);var y=[...document.querySelectorAll("[data-toc-link]")].flatMap(e=>{let t=p(e.hash),n=e.parentElement;return!t||!n?[]:[{heading:t,link:e,item:n,list:n.parentElement,subs:[...n.querySelectorAll("[data-toc-sub-link]")].flatMap(r=>{let u=p(r.hash),d=r.parentElement;return u&&d?[{heading:u,link:r,item:d}]:[]})}]}),w=y.at(0);if(w){let e=()=>{let t=Number.parseFloat(getComputedStyle(w.heading).scrollMarginTop)+1,n=y.findLast(s=>s.heading.checkVisibility()&&s.heading.getBoundingClientRect().top<=t)??w,r=n.subs.findLast(s=>s.heading.checkVisibility()&&s.heading.getBoundingClientRect().top<=t),u=y.indexOf(n),d=r===void 0?-1:n.subs.indexOf(r);for(let[s,l]of y.entries()){l.link.classList.toggle("wg_shellToc__link--active",l===n),l.item.classList.toggle("wg_shellToc__item--trail",l.list===n.list&&s<u),l.item.classList.toggle("wg_shellToc__item--current",l===n);for(let[h,a]of l.subs.entries())a.link.classList.toggle("wg_shellToc__subLink--active",a===r),a.item.classList.toggle("wg_shellToc__subItem--trail",l===n&&h<d),a.item.classList.toggle("wg_shellToc__subItem--current",a===r)}};addEventListener("scroll",e,{passive:!0}),addEventListener("resize",e),addEventListener("toggle",e,!0),e()}var I=new AbortController;for(let e of["wheel","touchmove","keydown","mousedown"])addEventListener(e,()=>I.abort(),{once:!0,passive:!0});var A=async()=>{await document.fonts.ready,v&&!I.signal.aborted&&(v.scrollIntoView({behavior:"instant"}),M(v)),document.documentElement.style.removeProperty("scroll-behavior")};document.readyState==="complete"?A():addEventListener("load",A,{once:!0});
+            )`,g.classList.add("wg_shell__cursorFace--visible")}))},c=h=>{if(!(e.matches&&h.pointerType==="mouse")){n();return}t.x=h.clientX,t.y=h.clientY,d()},l=()=>{g.classList.contains("wg_shell__cursorFace--visible")&&d()},a=()=>{if(g.classList.contains("wg_shell__cursorFace--visible"))try{sessionStorage.setItem(L,JSON.stringify({x:t.x,y:t.y}))}catch{}},u=()=>{try{let h=sessionStorage.getItem(L);if(sessionStorage.removeItem(L),h!==null&&e.matches){let r=JSON.parse(h);typeof r=="object"&&r!==null&&"x"in r&&"y"in r&&typeof r.x=="number"&&typeof r.y=="number"&&Number.isFinite(r.x)&&Number.isFinite(r.y)&&(t.x=r.x,t.y=r.y,d())}}catch{}};u(),document.addEventListener("pointermove",c,{passive:!0}),document.addEventListener("pointerdown",c,{passive:!0}),document.documentElement.addEventListener("pointerleave",n),addEventListener("blur",n),addEventListener("resize",l),addEventListener("pagehide",a),addEventListener("pageshow",u),e.addEventListener("change",i)}var v=m(location.hash),_=null,y=0,f=null,x=()=>{clearTimeout(y),f?.abort(),f=null,_?.classList.remove("wg_prose__headingText--highlighted"),_=null},M=e=>{x(),_=e===null?null:e.querySelector(".wg_prose__headingText"),_!==null&&(_.classList.add("wg_prose__headingText--highlighted"),y=window.setTimeout(x,3e3),f=new AbortController,document.addEventListener("scrollend",B,{signal:f.signal}))},B=e=>{e.target===document&&(clearTimeout(y),f?.abort(),f=null,y=window.setTimeout(x,3e3))},N=e=>{if(!(e.defaultPrevented||e.button!==0||e.metaKey||e.ctrlKey||e.shiftKey||e.altKey)&&e.currentTarget instanceof HTMLAnchorElement&&(e.currentTarget.target===""||e.currentTarget.target==="_self")&&!e.currentTarget.hasAttribute("download")&&e.currentTarget.origin===location.origin&&e.currentTarget.pathname===location.pathname&&e.currentTarget.search===location.search&&e.currentTarget.hash){let t=m(e.currentTarget.hash);e.currentTarget.hash===location.hash&&M(t)}},K=()=>{let e=m(location.hash);e?.scrollIntoView(),M(e)};for(let e of document.querySelectorAll("a[href]"))e.addEventListener("click",N);addEventListener("hashchange",K);var E=[...document.querySelectorAll("[data-toc-link]")].flatMap(e=>{let t=p(e.hash),n=e.parentElement;return!t||!n?[]:[{heading:t,link:e,item:n,list:n.parentElement,subs:[...n.querySelectorAll("[data-toc-sub-link]")].flatMap(i=>{let d=p(i.hash),c=i.parentElement;return d&&c?[{heading:d,link:i,item:c}]:[]})}]}),w=E.at(0);if(w){let e=()=>{let t=Number.parseFloat(getComputedStyle(w.heading).scrollMarginTop)+1,n=E.findLast(l=>l.heading.checkVisibility()&&l.heading.getBoundingClientRect().top<=t)??w,i=n.subs.findLast(l=>l.heading.checkVisibility()&&l.heading.getBoundingClientRect().top<=t),d=E.indexOf(n),c=i===void 0?-1:n.subs.indexOf(i);for(let[l,a]of E.entries()){let u=a===n&&i===void 0;a.link.classList.toggle("wg_shellToc__link--active",u),u?a.link.setAttribute("aria-current","location"):a.link.removeAttribute("aria-current"),a.item.classList.toggle("wg_shellToc__item--trail",a.list===n.list&&l<d),a.item.classList.toggle("wg_shellToc__item--current",a===n);for(let[h,r]of a.subs.entries())r.link.classList.toggle("wg_shellToc__subLink--active",r===i),r===i?r.link.setAttribute("aria-current","location"):r.link.removeAttribute("aria-current"),r.item.classList.toggle("wg_shellToc__subItem--trail",a===n&&h<c),r.item.classList.toggle("wg_shellToc__subItem--current",r===i)}};addEventListener("scroll",e,{passive:!0}),addEventListener("resize",e),addEventListener("toggle",e,!0),e()}var I=new AbortController;for(let e of["wheel","touchmove","keydown","mousedown"])addEventListener(e,()=>I.abort(),{once:!0,passive:!0});var A=async()=>{await document.fonts.ready,v&&!I.signal.aborted&&(v.scrollIntoView({behavior:"instant"}),M(v)),document.documentElement.style.removeProperty("scroll-behavior")};document.readyState==="complete"?A():addEventListener("load",A,{once:!0});

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "for-humanity",
-    "version": "0.2.1",
+    "version": "0.4.0",
     "description": "Documents written for humans to read: a docs kit with a sidebar, parts, sections and flowcharts, built on Hono and React",
     "keywords": [
         "docs",

package/src/cli.ts

@@ -7,14 +7,14 @@
 import {EventEmitter} from "node:events";
 import {existsSync, watch} from "node:fs";
 import {copyFile, mkdir, rm, writeFile} from "node:fs/promises";
-import {basename, dirname, join, relative, resolve} from "node:path";
+import {basename, dirname, extname, join, relative, resolve, sep} from "node:path";
 import {fileURLToPath, pathToFileURL} from "node:url";
 import {serve} from "@hono/node-server";
 import {serveStatic} from "@hono/node-server/serve-static";
 import {Hono} from "hono";
 import {toSSG} from "hono/ssg";
 import {createApp} from "@/app";
-import {asset_client_path, asset_favicon_path, asset_font_dir, asset_style_path} from "@/constant/asset";
+import {asset_client_path, asset_favicon_path, asset_font_dir, asset_media_extensions, asset_style_path} from "@/constant/asset";
 import {cli_config_file_name, cli_default_command, cli_default_docs_dir, cli_dev_port} from "@/constant/cli";
 import {copy_error_config, copy_error_font_preload, copy_error_prefix, copy_error_unknown_command} from "@/constant/copy";
 import {font_brand_css, font_cache_control, font_mono_css, font_sans_css, font_sans_preload_file} from "@/constant/font";
@@ -85,7 +85,7 @@ const main = async () => {
     const fontCss = [sans.css, mono.css, brand.css].join("\n");
     const stylePath = toAssetPath({path: asset_style_path, file: join(kitRoot, "dist/cli.css")});
     const clientPath = toAssetPath({path: asset_client_path, file: join(kitRoot, "dist/client.js")});
-    const files = new Map([
+    const kitFiles = new Map([
         [stylePath, join(kitRoot, "dist/cli.css")],
         [clientPath, join(kitRoot, "dist/client.js")],
         [asset_favicon_path, join(kitRoot, "src/asset/favicon.svg")],
@@ -93,7 +93,8 @@ const main = async () => {
         ...mono.files,
         ...brand.files,
     ]);
-    const processor = createProcessor({site: siteConfig, root: docsRoot});
+    const files = new Map(kitFiles);
+    const processor = createProcessor({site: siteConfig, root: docsRoot, files});
     const [docs, home] = await Promise.all([readDocs({root: docsRoot, processor}), readHome({root: docsRoot, processor})]);
     const store = {docs, home};
     const app = createApp({
@@ -132,20 +133,30 @@ const main = async () => {
      * 재처리 실패 시 직전 정상 문서 유지
      */
     const handleDocsChange = async (_event: string, filename: string | null) => {
-        if (filename !== null && !/\.mdx?$/i.test(filename)) {
-            return;
+        if (filename !== null) {
+            const segments = filename.split(sep);
+            // 출력·설치 폴더는 제외 · 실패한 참조의 파일이 뒤늦게 생겨도 다시 처리
+            if (segments.includes("dist") || segments.includes("node_modules") || (!/\.mdx?$/i.test(filename) && !asset_media_extensions.has(extname(filename).toLowerCase()))) {
+                return;
+            }
         }
 
         const currentGeneration = ++generation;
 
         try {
-            const [docs, home] = await Promise.all([readDocs({root: docsRoot, processor}), readHome({root: docsRoot, processor})]);
+            const nextFiles = new Map(kitFiles);
+            const nextProcessor = createProcessor({site: siteConfig, root: docsRoot, files: nextFiles});
+            const [docs, home] = await Promise.all([readDocs({root: docsRoot, processor: nextProcessor}), readHome({root: docsRoot, processor: nextProcessor})]);
 
             // 최신 변경의 처리 결과만 반영
             if (currentGeneration !== generation) {
                 return;
             }
 
+            files.clear();
+            for (const entry of nextFiles) {
+                files.set(...entry);
+            }
             store.docs = docs;
             store.home = home;
             reload.emit("change");

package/src/client.ts

@@ -275,12 +275,23 @@ if (firstSection) {
         const currentSubIndex = sub === undefined ? -1 : current.subs.indexOf(sub);
 
         for (const [index, section] of tocSections.entries()) {
-            section.link.classList.toggle("wg_shellToc__link--active", section === current);
+            const active = section === current && sub === undefined;
+            section.link.classList.toggle("wg_shellToc__link--active", active);
+            if (active) {
+                section.link.setAttribute("aria-current", "location");
+            } else {
+                section.link.removeAttribute("aria-current");
+            }
             section.item.classList.toggle("wg_shellToc__item--trail", section.list === current.list && index < currentIndex);
             section.item.classList.toggle("wg_shellToc__item--current", section === current);
 
             for (const [subIndex, item] of section.subs.entries()) {
                 item.link.classList.toggle("wg_shellToc__subLink--active", item === sub);
+                if (item === sub) {
+                    item.link.setAttribute("aria-current", "location");
+                } else {
+                    item.link.removeAttribute("aria-current");
+                }
                 item.item.classList.toggle("wg_shellToc__subItem--trail", section === current && subIndex < currentSubIndex);
                 item.item.classList.toggle("wg_shellToc__subItem--current", item === sub);
             }