for-humanity 0.1.0

package/src/client.ts

@@ -0,0 +1,322 @@
+/*
+ * 브라우저 동작 · 모바일 탐색, 커서 장식, 읽는 절, hash 위치 보정
+ * 서버 HTML의 data-* 연결 · React hydration 없음
+ */
+
+import {heading_highlight_hold_ms} from "@/component/widget/prose/_constant/heading-highlight";
+import {cursor_face_offset_px, cursor_face_storage_key} from "@/component/widget/shell/_constant/cursor-face";
+import {reading_line_slack_px} from "@/component/widget/shell/_constant/reading-line";
+import {bindMobileNavigation} from "@/component/widget/shell/_function/bind-mobile-navigation";
+import {findHashTarget} from "@/util/dom/find-hash-target";
+import {revealHashTarget} from "@/util/dom/reveal-hash-target";
+
+bindMobileNavigation();
+
+const cursorFace = document.querySelector<HTMLImageElement>("[data-cursor-face]");
+
+if (cursorFace) {
+    const cursorMedia = matchMedia("(hover: hover) and (pointer: fine) and (prefers-reduced-motion: no-preference)");
+    const position = {x: 0, y: 0, frame: 0};
+
+    /**
+     * 터치 전환과 화면 이탈 시 예약된 이동도 취소해 장식이 다시 나타나지 않게 함
+     */
+    const handleCursorHide = () => {
+        cancelAnimationFrame(position.frame);
+        position.frame = 0;
+        cursorFace.classList.remove("wg_shell__cursorFace--visible");
+    };
+
+    /**
+     * 비활성 전환에서만 숨김 · 활성화 알림이 새 마우스 이동을 취소하지 않도록 함
+     */
+    const handleCursorMediaChange = () => {
+        if (!cursorMedia.matches) {
+            handleCursorHide();
+        }
+    };
+
+    /**
+     * 이동·화면 크기 변경·문서 진입에 같은 위치 계산 적용 · 화면 갱신마다 한 번만 반영
+     */
+    const renderCursorFace = () => {
+        if (position.frame !== 0) {
+            return;
+        }
+
+        position.frame = requestAnimationFrame(() => {
+            position.frame = 0;
+
+            // 포인터 좌표는 실행 중에만 결정 · transform으로 문서 재배치 방지
+            cursorFace.style.transform = `translate3d(
+                ${Math.max(0, Math.min(position.x + cursor_face_offset_px, document.documentElement.clientWidth - cursorFace.width - cursor_face_offset_px))}px,
+                ${Math.max(0, Math.min(position.y + cursor_face_offset_px, document.documentElement.clientHeight - cursorFace.height - cursor_face_offset_px))}px,
+                0
+            )`;
+            cursorFace.classList.add("wg_shell__cursorFace--visible");
+        });
+    };
+
+    /**
+     * 누른 상태도 마우스 입력으로 처리 · 클릭·텍스트 선택 중에도 얼굴 유지
+     */
+    const handleDocumentPointer = (event: PointerEvent) => {
+        const isMouse = cursorMedia.matches && event.pointerType === "mouse";
+
+        if (!isMouse) {
+            handleCursorHide();
+
+            return;
+        }
+
+        position.x = event.clientX;
+        position.y = event.clientY;
+        renderCursorFace();
+    };
+
+    /**
+     * 이미 보이는 얼굴을 새 화면 크기에 맞춰 이동 · 추가 마우스 이동 불필요
+     */
+    const handleCursorResize = () => {
+        if (cursorFace.classList.contains("wg_shell__cursorFace--visible")) {
+            renderCursorFace();
+        }
+    };
+
+    /**
+     * 전체 페이지 이동에서도 마지막 좌표 유지 · 저장 실패는 기본 마우스 동작에 영향 없음
+     */
+    const handlePageHide = () => {
+        if (!cursorFace.classList.contains("wg_shell__cursorFace--visible")) {
+            return;
+        }
+
+        try {
+            sessionStorage.setItem(cursor_face_storage_key, JSON.stringify({x: position.x, y: position.y}));
+        } catch {
+            // 저장소가 막힌 환경에서도 클릭·선택과 현재 페이지의 장식 유지
+        }
+    };
+
+    /**
+     * 첫 진입과 BFCache 복귀에서 좌표를 한 번 소비 · 이전 문서의 위치가 남지 않도록 삭제
+     */
+    const handlePageShow = () => {
+        try {
+            const stored = sessionStorage.getItem(cursor_face_storage_key);
+
+            sessionStorage.removeItem(cursor_face_storage_key);
+
+            if (stored !== null && cursorMedia.matches) {
+                const point: unknown = JSON.parse(stored);
+                // 속성 타입의 좁히기를 유지하도록 저장소 검증과 사용을 같은 분기에 둠
+                if (
+                    typeof point === "object" &&
+                    point !== null &&
+                    "x" in point &&
+                    "y" in point &&
+                    typeof point.x === "number" &&
+                    typeof point.y === "number" &&
+                    Number.isFinite(point.x) &&
+                    Number.isFinite(point.y)
+                ) {
+                    position.x = point.x;
+                    position.y = point.y;
+                    renderCursorFace();
+                }
+            }
+        } catch {
+            // 저장 실패나 잘못된 좌표는 무시하고 다음 실제 마우스 입력에서 표시
+        }
+    };
+
+    handlePageShow();
+
+    document.addEventListener("pointermove", handleDocumentPointer, {passive: true});
+    document.addEventListener("pointerdown", handleDocumentPointer, {passive: true});
+    document.documentElement.addEventListener("pointerleave", handleCursorHide);
+    addEventListener("blur", handleCursorHide);
+    addEventListener("resize", handleCursorResize);
+    addEventListener("pagehide", handlePageHide);
+    addEventListener("pageshow", handlePageShow);
+    cursorMedia.addEventListener("change", handleCursorMediaChange);
+}
+
+const hashTarget = revealHashTarget(location.hash);
+
+// 값 조립이 아닌 현재 강조의 수명 상태 · 새 이동은 이전 타이머를 취소
+let highlightedHeading: HTMLElement | null = null;
+let highlightTimer = 0;
+let highlightScroll: AbortController | null = null;
+
+/**
+ * 강조 해제와 도착 감시 정리 · 다음 앵커의 오래된 타이머 개입 방지
+ */
+const clearHeadingHighlight = () => {
+    clearTimeout(highlightTimer);
+    highlightScroll?.abort();
+    highlightScroll = null;
+    highlightedHeading?.classList.remove("wg_prose__headingText--highlighted");
+    highlightedHeading = null;
+};
+
+/**
+ * 도착한 제목만 잠시 강조 · 같은 대상 재클릭도 유지 시간 재시작
+ */
+const highlightHeading = (target: HTMLElement | null) => {
+    clearHeadingHighlight();
+    highlightedHeading = target === null ? null : target.querySelector<HTMLElement>(".wg_prose__headingText");
+
+    if (highlightedHeading === null) {
+        return;
+    }
+
+    highlightedHeading.classList.add("wg_prose__headingText--highlighted");
+    highlightTimer = window.setTimeout(clearHeadingHighlight, heading_highlight_hold_ms);
+    highlightScroll = new AbortController();
+
+    // 부드러운 스크롤이 끝난 뒤에도 3초 확보 · 움직이지 않거나 scrollend가 없으면 위 타이머 사용
+    document.addEventListener("scrollend", handleHighlightArrival, {signal: highlightScroll.signal});
+};
+
+/**
+ * 본문 스크롤의 첫 도착에서 유지 시간 갱신 · 사이드바 스크롤은 제외
+ */
+const handleHighlightArrival = (event: Event) => {
+    if (event.target !== document) {
+        return;
+    }
+
+    clearTimeout(highlightTimer);
+    highlightScroll?.abort();
+    highlightScroll = null;
+    highlightTimer = window.setTimeout(clearHeadingHighlight, heading_highlight_hold_ms);
+};
+
+/**
+ * 같은 hash를 다시 눌러도 접힌 대상 공개 · 기본 링크 이동 유지
+ */
+const handleHashClick = (event: MouseEvent) => {
+    if (event.defaultPrevented || event.button !== 0 || event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) {
+        return;
+    }
+
+    if (
+        event.currentTarget instanceof HTMLAnchorElement &&
+        (event.currentTarget.target === "" || event.currentTarget.target === "_self") &&
+        !event.currentTarget.hasAttribute("download") &&
+        event.currentTarget.origin === location.origin &&
+        event.currentTarget.pathname === location.pathname &&
+        event.currentTarget.search === location.search &&
+        event.currentTarget.hash
+    ) {
+        const target = revealHashTarget(event.currentTarget.hash);
+
+        if (event.currentTarget.hash === location.hash) {
+            highlightHeading(target);
+        }
+    }
+};
+
+/**
+ * hash 변경의 숨은 대상 공개와 위치 보정
+ */
+const handleHashChange = () => {
+    const target = revealHashTarget(location.hash);
+
+    target?.scrollIntoView();
+    highlightHeading(target);
+};
+
+for (const link of document.querySelectorAll<HTMLAnchorElement>("a[href]")) {
+    link.addEventListener("click", handleHashClick);
+}
+
+addEventListener("hashchange", handleHashChange);
+
+// 목차 링크와 실제 제목 연결
+const tocSections = [...document.querySelectorAll<HTMLAnchorElement>("[data-toc-link]")].flatMap((link) => {
+    const heading = findHashTarget(link.hash);
+    const item = link.parentElement;
+
+    if (!heading || !item) {
+        return [];
+    }
+
+    return [
+        {
+            heading,
+            link,
+            item,
+            list: item.parentElement,
+            subs: [...item.querySelectorAll<HTMLAnchorElement>("[data-toc-sub-link]")].flatMap((sub) => {
+                const subHeading = findHashTarget(sub.hash);
+                const subItem = sub.parentElement;
+
+                return subHeading && subItem ? [{heading: subHeading, link: sub, item: subItem}] : [];
+            }),
+        },
+    ];
+});
+const firstSection = tocSections.at(0);
+
+if (firstSection) {
+    /**
+     * 읽는 선 기준 절·소제목 표시
+     * 기준: 제목의 scroll-margin-top + reading_line_slack_px
+     */
+    const markActive = () => {
+        // scroll-margin-top 계산값: CSS px
+        const line = Number.parseFloat(getComputedStyle(firstSection.heading).scrollMarginTop) + reading_line_slack_px;
+        // 접힌 Details 안 제목은 좌표가 남아도 현재 위치에서 제외
+        const current = tocSections.findLast((section) => section.heading.checkVisibility() && section.heading.getBoundingClientRect().top <= line) ?? firstSection;
+        const sub = current.subs.findLast((item) => item.heading.checkVisibility() && item.heading.getBoundingClientRect().top <= line);
+        const currentIndex = tocSections.indexOf(current);
+        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);
+            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);
+                item.item.classList.toggle("wg_shellToc__subItem--trail", section === current && subIndex < currentSubIndex);
+                item.item.classList.toggle("wg_shellToc__subItem--current", item === sub);
+            }
+        }
+    };
+
+    addEventListener("scroll", markActive, {passive: true});
+    addEventListener("resize", markActive);
+    addEventListener("toggle", markActive, true);
+    markActive();
+}
+
+const userScroll = new AbortController();
+
+for (const type of ["wheel", "touchmove", "keydown", "mousedown"]) {
+    addEventListener(type, () => userScroll.abort(), {once: true, passive: true});
+}
+
+/**
+ * 글꼴 로드 후 hash 위치 보정 · 사용자 입력 시 자동 이동 취소
+ * 초기 smooth scroll과 보정의 충돌 방지 · 보정 후 CSS 동작 복원
+ */
+const settleHashScroll = async () => {
+    await document.fonts.ready;
+
+    if (hashTarget && !userScroll.signal.aborted) {
+        hashTarget.scrollIntoView({behavior: "instant"});
+        highlightHeading(hashTarget);
+    }
+
+    document.documentElement.style.removeProperty("scroll-behavior");
+};
+
+// 글꼴 요청 완료 시점 보장 · load 후 fonts.ready
+if (document.readyState === "complete") {
+    settleHashScroll();
+} else {
+    addEventListener("load", settleHashScroll, {once: true});
+}

package/src/component/widget/prose/_constant/heading-highlight.ts

@@ -0,0 +1,4 @@
+/**
+ * 앵커 이동 후 제목 강조 유지 시간 · 이후 CSS로 서서히 해제
+ */
+export const heading_highlight_hold_ms = 3000;

package/src/component/widget/prose/_constant/section.ts

@@ -0,0 +1,7 @@
+/**
+ * 목차 대상 제목 깊이 · h2 절, h3 소제목
+ */
+export const section_heading_depth = {
+    section: 2,
+    sub: 3,
+} as const;

package/src/component/widget/prose/_constant/status.ts

@@ -0,0 +1,9 @@
+/**
+ * 상태 문구 뒤 날짜 패턴 · YYYY-MM-DD
+ */
+export const status_date_pattern = String.raw`\d{4}-\d{2}-\d{2}`;
+
+/**
+ * 미등록 날짜 상태 후보 · 등록 문구 치환 뒤 남은 괄호 문구
+ */
+export const status_candidate_pattern = new RegExp(String.raw`\([^()\n]*${status_date_pattern}\)`, "g");

package/src/component/widget/prose/_function/has-block-content.ts

@@ -0,0 +1,30 @@
+import type {Nodes} from "mdast";
+
+/**
+ * 부품 본문의 내용 판정 · 참조 정의·주석·빈 텍스트와 빈 구조 제외
+ * 이미지·표·구분선·주석 외 원시 HTML은 본문 요소
+ */
+export const hasBlockContent = (node: Nodes): boolean => {
+    if (node.type === "definition") {
+        return false;
+    }
+
+    if (node.type === "html") {
+        // HTML의 빈 주석·대체 닫힘·미종결 주석 포함
+        return node.value.replace(/<!--(?:>|->|[\s\S]*?(?:--!?>|$))/g, "").trim() !== "";
+    }
+
+    if ("value" in node) {
+        return node.value.trim() !== "";
+    }
+
+    if (node.type === "table" || node.type === "textDirective") {
+        return true;
+    }
+
+    if ("children" in node) {
+        return node.children.some(hasBlockContent);
+    }
+
+    return true;
+};

package/src/component/widget/prose/_function/rehype-head.ts

@@ -0,0 +1,31 @@
+import type {Root} from "hast";
+import type {VFile} from "vfile";
+import {section_heading_depth} from "@/component/widget/prose/_constant/section";
+
+/**
+ * name 제목과 첫 절 앞 본문의 공통 머리 · README는 원문의 h1 사용
+ */
+export const rehypeHead = () => (tree: Root, file: VFile) => {
+    const frontmatter = file.data.fh?.frontmatter;
+
+    const firstSection = tree.children.findIndex((node) => node.type === "element" && node.tagName === `h${section_heading_depth.section}`);
+    const leadEnd = firstSection === -1 ? tree.children.length : firstSection;
+
+    if (frontmatter === undefined && leadEnd === 0) {
+        return;
+    }
+
+    tree.children = [
+        {
+            type: "element",
+            tagName: "header",
+            properties: {className: ["wg_prose__head"]},
+            children: [...tree.children.slice(0, leadEnd).filter((node) => node.type !== "doctype")],
+        },
+        ...tree.children.slice(leadEnd),
+    ];
+
+    if (frontmatter !== undefined && tree.children[0].type === "element") {
+        tree.children[0].children.unshift({type: "element", tagName: "h1", properties: {}, children: [{type: "text", value: frontmatter.name}]});
+    }
+};

package/src/component/widget/prose/_function/rehype-sections/_to-section-headings.ts

@@ -0,0 +1,20 @@
+import type {Element, Root} from "hast";
+import {section_heading_depth} from "@/component/widget/prose/_constant/section";
+
+/**
+ * 목차 대상 h2·h3 · 중첩 블록까지 문서 순서 수집
+ * rehype-heading-ids의 순회 순서와 일치
+ */
+export const toSectionHeadings = (node: Root | Element): Element[] => {
+    return node.children.flatMap((child) => {
+        if (child.type !== "element") {
+            return [];
+        }
+
+        if (child.tagName === `h${section_heading_depth.section}` || child.tagName === `h${section_heading_depth.sub}`) {
+            return [child];
+        }
+
+        return toSectionHeadings(child);
+    });
+};

package/src/component/widget/prose/_function/rehype-sections/rehype-sections.ts

@@ -0,0 +1,21 @@
+import type {Root} from "hast";
+import type {VFile} from "vfile";
+import {toSectionHeadings} from "@/component/widget/prose/_function/rehype-sections/_to-section-headings";
+import type {DocSection} from "@/component/widget/prose/_type/doc-section";
+
+/**
+ * h2·h3의 가름 메타데이터 수집 · 작성한 제목은 그대로 유지
+ * id·목차 텍스트는 앞 단계의 rehype-heading-ids 소유
+ * file.data.fh.sections는 headings의 h2·h3 순서와 일치
+ */
+export const rehypeSections = () => (tree: Root, file: VFile) => {
+    if (file.data.fh === undefined) {
+        return;
+    }
+
+    file.data.fh.sections = toSectionHeadings(tree).map(
+        (heading): DocSection => ({
+            part: typeof heading.properties.dataPart === "string" ? heading.properties.dataPart : undefined,
+        }),
+    );
+};

package/src/component/widget/prose/_function/rehype-tables.ts

@@ -0,0 +1,22 @@
+import type {Root} from "hast";
+import {SKIP, visit} from "unist-util-visit";
+
+/**
+ * 넓은 표의 내부 가로 스크롤 래퍼
+ */
+export const rehypeTables = () => (tree: Root) => {
+    visit(tree, "element", (node, index, parent) => {
+        if (node.tagName !== "table" || parent === undefined || index === undefined) {
+            return;
+        }
+
+        parent.children[index] = {
+            type: "element",
+            tagName: "div",
+            properties: {className: ["wg_prose__table"]},
+            children: [node],
+        };
+
+        return [SKIP, index + 1];
+    });
+};

package/src/component/widget/prose/_function/remark-blocks.ts

@@ -0,0 +1,112 @@
+import type {Root} from "mdast";
+import {toString as toPlainText} from "mdast-util-to-string";
+import {visit} from "unist-util-visit";
+import type {VFile} from "vfile";
+import {section_heading_depth} from "@/component/widget/prose/_constant/section";
+import {hasBlockContent} from "@/component/widget/prose/_function/has-block-content";
+import {copy_error_directive_syntax} from "@/constant/copy";
+
+/**
+ * Note·Details의 제목·본문·속성·닫힘 계약
+ * label은 첫 자식 · summary는 Details의 첫 요소 · 원문 위치는 오류 기준
+ */
+export const remarkBlocks = () => (tree: Root, file: VFile) => {
+    const source = String(file.value);
+
+    visit(tree, (node, _index, parent) => {
+        if (node.type === "leafDirective" && node.name === "part" && parent?.type !== "root") {
+            file.fail(`${copy_error_directive_syntax}: part · 문서 최상위에 작성`, node);
+        }
+
+        if (node.type !== "containerDirective" && node.type !== "leafDirective" && node.type !== "textDirective") {
+            return;
+        }
+
+        if (node.name !== "note" && node.name !== "details") {
+            return;
+        }
+
+        if (node.type !== "containerDirective") {
+            file.fail(`${copy_error_directive_syntax}: ${node.name} · ::: 블록으로 작성`, node);
+        }
+
+        const label = node.children.at(0);
+
+        if (label?.type !== "paragraph" || label.data?.directiveLabel !== true || label.children.some((child) => child.type !== "text")) {
+            file.fail(`${copy_error_directive_syntax}: ${node.name} · 일반 텍스트 제목 필수`, node);
+        }
+
+        const title = toPlainText(label).trim();
+
+        if (title === "") {
+            file.fail(`${copy_error_directive_syntax}: ${node.name} · 비어 있지 않은 제목 필수`, node);
+        }
+
+        if (!node.children.slice(1).some(hasBlockContent)) {
+            file.fail(`${copy_error_directive_syntax}: ${node.name} · 본문 필수`, node);
+        }
+
+        const unsupported = node.attributes ? Object.keys(node.attributes).find((key) => node.name !== "details" || key !== "open") : undefined;
+
+        if (unsupported !== undefined) {
+            file.fail(`${copy_error_directive_syntax}: ${node.name} · 미지원 속성 ${unsupported}`, node);
+        }
+
+        const open = node.attributes?.open;
+        const attributeSource = source.slice(label.position?.end.offset, node.position?.end.offset).split(/\r?\n/, 1)[0].trim();
+
+        // 속성 정규화 이전의 표기 · 중복 open과 open="" 거부
+        if (attributeSource !== "" && (node.name !== "details" || !/^\{[ \t]*open[ \t]*\}$/.test(attributeSource))) {
+            file.fail(`${copy_error_directive_syntax}: ${node.name} · 허용 속성은 Details의 {open}, 나머지는 생략`, node);
+        }
+
+        const original = source.slice(node.position?.start.offset, node.position?.end.offset);
+        const opening = /^(:{3,})/.exec(original);
+        const closing = /(?:^|\n)[ \t>]*(:{3,})[ \t]*\r?$/.exec(original);
+
+        if (
+            opening === null ||
+            closing === null ||
+            closing.index + closing[0].length !== original.length ||
+            closing[1].length < opening[1].length ||
+            node.position?.end.offset === node.children.at(-1)?.position?.end.offset
+        ) {
+            file.fail(`${copy_error_directive_syntax}: ${node.name} · 블록을 닫는 fence 필수`, node);
+        }
+
+        visit(node, "heading", (heading) => {
+            if (heading.depth <= section_heading_depth.section) {
+                file.fail(`${copy_error_directive_syntax}: ${node.name} · #·## 제목은 부품 밖에 작성`, heading);
+            }
+        });
+
+        // 코드 안의 :::가 container를 먼저 닫은 경우 · 더 긴 바깥 fence로 구분
+        visit(node, "code", (code) => {
+            const originalCode = source.slice(code.position?.start.offset, code.position?.end.offset);
+            const codeOpening = /^ {0,3}(`{3,}|~{3,})/.exec(originalCode);
+            const codeClosing = /(?:^|\n)[ \t>]*(`{3,}|~{3,})[ \t]*\r?$/.exec(originalCode);
+
+            if (
+                codeOpening !== null &&
+                (codeClosing === null ||
+                    codeClosing.index + codeClosing[0].length !== originalCode.length ||
+                    codeClosing[1][0] !== codeOpening[1][0] ||
+                    codeClosing[1].length < codeOpening[1].length)
+            ) {
+                file.fail(`${copy_error_directive_syntax}: ${node.name} · 코드 fence를 닫고, 코드 안의 :보다 긴 바깥 fence 사용`, code);
+            }
+        });
+
+        label.children = [{type: "text", value: title}];
+        label.data = {
+            ...label.data,
+            hName: node.name === "note" ? "strong" : "summary",
+            hProperties: {className: [node.name === "note" ? "wg_prose__noteTitle" : "wg_prose__detailsSummary"]},
+        };
+        node.data = {
+            ...node.data,
+            hName: node.name === "note" ? "aside" : "details",
+            hProperties: node.name === "note" ? {className: ["wg_prose__note"], ariaLabel: title} : {className: ["wg_prose__details"], open: open === ""},
+        };
+    });
+};

package/src/component/widget/prose/_function/remark-flow.ts

@@ -0,0 +1,26 @@
+import type {Root} from "mdast";
+import {visit} from "unist-util-visit";
+import type {VFile} from "vfile";
+import {copy_error_flow} from "@/constant/copy";
+import {renderFlow} from "@/util/mermaid/render-flow";
+
+/**
+ * Mermaid → 격자 SVG · beautiful-mermaid 기반
+ * 실패 시 파일·줄을 포함한 빌드 오류
+ */
+export const remarkFlow = () => (tree: Root, file: VFile) => {
+    visit(tree, "code", (node, index, parent) => {
+        if (node.lang !== "mermaid" || parent === undefined || index === undefined) {
+            return;
+        }
+
+        try {
+            parent.children[index] = {
+                type: "html",
+                value: `<div class="wg_prose__flow">${renderFlow(node.value)}</div>`,
+            };
+        } catch (error) {
+            file.fail(`${copy_error_flow}: ${error instanceof Error ? error.message : String(error)}`, node);
+        }
+    });
+};

package/src/component/widget/prose/_function/remark-links.ts

@@ -0,0 +1,33 @@
+import {existsSync} from "node:fs";
+import {dirname, posix, relative, resolve} from "node:path";
+import type {Root} from "mdast";
+import {visit} from "unist-util-visit";
+import type {VFile} from "vfile";
+import {copy_warn_broken_link} from "@/constant/copy";
+
+/**
+ * 상대 Markdown 링크 → 사이트 URL · query·hash 원문 유지
+ * 외부·절대 URL과 같은 페이지 hash 유지 · 없는 파일은 터미널 경고
+ */
+export const remarkLinks = (options: {root: string}) => (tree: Root, file: VFile) => {
+    const here = dirname(relative(options.root, file.path));
+
+    visit(tree, (node) => {
+        if (node.type !== "link" && node.type !== "definition") {
+            return;
+        }
+
+        // 셋째 capture: query·hash 접미사 · 파일 확인과 경로 정규화에서 제외
+        const match = /^(?![a-z]+:|\/|#)([^#?]+)(\.mdx?)([?#].*|)$/i.exec(node.url);
+
+        if (match) {
+            if (!existsSync(resolve(dirname(file.path), `${match[1]}${match[2]}`))) {
+                file.message(`${copy_warn_broken_link}: ${node.url}`, node);
+            }
+
+            const target = posix.join(here, `${match[1]}${match[2]}`).toLowerCase();
+
+            node.url = target === "readme.md" ? `/${match[3]}` : `/${posix.join(here, match[1]).toLowerCase()}/${match[3]}`;
+        }
+    });
+};

package/src/component/widget/prose/_function/remark-parts.ts

@@ -0,0 +1,26 @@
+import type {Root} from "mdast";
+import {toString as toPlainText} from "mdast-util-to-string";
+import {section_heading_depth} from "@/component/widget/prose/_constant/section";
+
+/**
+ * ::part[이름]의 본문 가름과 다음 h2의 data-part
+ * rehype-sections에서 같은 지점의 목차 묶음 생성
+ */
+export const remarkParts = () => (tree: Root) => {
+    for (const [index, node] of tree.children.entries()) {
+        if (node.type !== "leafDirective" || node.name !== "part") {
+            continue;
+        }
+
+        const section = tree.children.slice(index + 1).find((next) => next.type === "heading" && next.depth === section_heading_depth.section);
+
+        node.data = {hName: "div", hProperties: {className: ["wg_prose__part"]}};
+
+        if (section) {
+            section.data = {
+                ...section.data,
+                hProperties: {...section.data?.hProperties, dataPart: toPlainText(node).trim()},
+            };
+        }
+    }
+};