for-humanity 0.1.0

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

@@ -0,0 +1,59 @@
+import {escape as escapeHtml, escapeRegExp} from "es-toolkit/string";
+import type {Root} from "mdast";
+import {findAndReplace, type RegExpMatchObject} from "mdast-util-find-and-replace";
+import type {VFile} from "vfile";
+import {status_candidate_pattern, status_date_pattern} from "@/component/widget/prose/_constant/status";
+import {copy_warn_unknown_status} from "@/constant/copy";
+import type {SiteConfig} from "@/type/site-config";
+
+/**
+ * 설정 문구의 상태 표지 변환 · 괄호 제거 · 제목·링크 제외
+ * 미등록 날짜 문구는 파일 경고 · remark-report에서 출력
+ */
+export const remarkStatus = (options: {status: SiteConfig["status"]}) => {
+    const statuses = options.status.toSorted((a, b) => b.phrase.length - a.phrase.length);
+    const phrases = statuses.map((item) => [escapeRegExp(item.phrase), ...(item.date ? [`(?: ${status_date_pattern})?`] : [])].join("")).join("|");
+    const pattern = new RegExp(String.raw`\((${phrases})\)|(${phrases})`, "g");
+    const ignore = ["link", "linkReference", "heading"];
+
+    return (tree: Root, file: VFile) => {
+        findAndReplace(
+            tree,
+            [
+                pattern,
+                (_match: string, inParens: string | undefined, bare: string | undefined) => {
+                    const text = inParens ?? bare;
+                    const item = statuses.find((status) => text?.startsWith(status.phrase));
+
+                    // findAndReplace의 false: 원문 유지
+                    if (text === undefined || item === undefined) {
+                        return false;
+                    }
+
+                    return {
+                        type: "html",
+                        value: `<span class="wg_prose__pill wg_prose__pill--${item.kind}">${escapeHtml(text)}</span>`,
+                    };
+                },
+            ],
+            {ignore},
+        );
+
+        findAndReplace(
+            tree,
+            [
+                status_candidate_pattern,
+                (match: string, info: RegExpMatchObject) => {
+                    // 치환된 텍스트에 position 부재 · 위치가 남은 가까운 조상 기준
+                    file.message(
+                        `${copy_warn_unknown_status}: ${match}`,
+                        info.stack.findLast((node) => node.position !== undefined),
+                    );
+
+                    return false;
+                },
+            ],
+            {ignore},
+        );
+    };
+};

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

@@ -0,0 +1,16 @@
+import type {Root} from "mdast";
+import {visit} from "unist-util-visit";
+
+/**
+ * 인라인 hex 색 값의 칩 표시
+ * 문서별 색은 --wg-prose-chip-color로 전달 · 고정 스타일시트 값 불가
+ */
+export const remarkSwatch = () => (tree: Root) => {
+    visit(tree, "inlineCode", (node) => {
+        if (/^#[0-9a-f]{3,8}$/i.test(node.value.trim())) {
+            node.data = {
+                hProperties: {className: ["wg_prose__color"], style: `--wg-prose-chip-color: ${node.value.trim()}`},
+            };
+        }
+    });
+};

package/src/component/widget/prose/_function/remark-unknown-directives.ts

@@ -0,0 +1,25 @@
+import type {Root} from "mdast";
+import {SKIP, visit} from "unist-util-visit";
+import type {VFile} from "vfile";
+import {copy_error_unknown_directive} from "@/constant/copy";
+
+/**
+ * hName 없는 블록 지시문은 작성 오류
+ * textDirective는 원문 복원 · 예:이것 같은 일반 문장의 오인 방지
+ */
+export const remarkUnknownDirectives = () => (tree: Root, file: VFile) => {
+    visit(tree, (node, index, parent) => {
+        if (node.type === "textDirective" && parent !== undefined && index !== undefined) {
+            parent.children[index] = {
+                type: "text",
+                value: String(file.value).slice(node.position?.start.offset, node.position?.end.offset),
+            };
+
+            return SKIP;
+        }
+
+        if ((node.type === "leafDirective" || node.type === "containerDirective") && node.data?.hName === undefined) {
+            file.fail(`${copy_error_unknown_directive}: ${node.name}`, node);
+        }
+    });
+};

package/src/component/widget/prose/_type/doc-section.ts

@@ -0,0 +1,9 @@
+/**
+ * h2·h3의 가름 · 문서 순서
+ */
+export interface DocSection {
+    /**
+     * 이 절에서 시작하는 가름 이름
+     */
+    part?: string;
+}

package/src/component/widget/prose/wg-prose.css

@@ -0,0 +1,381 @@
+/*
+ * Markdown 본문과 생성 부품의 표현
+ * 요소 선택자는 소유 root 안에 한정
+ */
+.wg_prose__root {
+    /* stylelint-disable selector-disallowed-list -- Markdown 생성 태그 영역 */
+    & h1 {
+        margin: 0 0 var(--app-space-stack);
+        color: var(--app-color-text-strong);
+        font-size: var(--app-font-size-title);
+        font-weight: var(--app-font-weight-title);
+        line-height: var(--app-line-height-title);
+        letter-spacing: var(--app-letter-spacing-title);
+        text-wrap: balance;
+
+        /* 문서 탐색 라벨과 같은 글자 위쪽 기준 · 글꼴 크기별 내부 여백 제거 */
+        text-box: trim-start cap alphabetic;
+    }
+
+    & p {
+        margin: 0 0 var(--app-space-stack);
+    }
+
+    & img {
+        max-width: 100%;
+        height: auto;
+        vertical-align: middle;
+    }
+
+    /* 제목 아래 첫 문단 · 소개 크기 */
+    & h1 + p {
+        font-size: var(--app-font-size-lead);
+    }
+
+    & h2 {
+        margin: var(--app-space-section) 0 var(--app-space-stack);
+        padding-top: var(--app-space-block);
+        border-top: 1px dotted var(--app-color-border);
+        color: var(--app-color-text-strong);
+        font-size: var(--app-font-size-section);
+        font-weight: var(--app-font-weight-strong);
+        line-height: var(--app-line-height-heading);
+        letter-spacing: var(--app-letter-spacing-heading);
+        text-wrap: balance;
+        scroll-margin-top: var(--app-space-anchor);
+    }
+
+    /* 머리 아래 첫 절의 중복 구분선 제거 */
+    & .wg_prose__head + h2 {
+        margin-top: var(--app-space-group);
+        padding-top: 0;
+        border-top: 0;
+    }
+
+    /* 가름 아래 절의 중복 구분선 제거 */
+    & .wg_prose__part + h2 {
+        margin-top: var(--app-space-block);
+        padding-top: 0;
+        border-top: 0;
+    }
+
+    & h3 {
+        margin: var(--app-space-group) 0 var(--app-space-inline);
+        color: var(--app-color-text-strong);
+        font-size: var(--app-font-size-lead);
+        font-weight: var(--app-font-weight-strong);
+        line-height: var(--app-line-height-tight);
+        scroll-margin-top: var(--app-space-anchor);
+    }
+
+    & h4 {
+        margin: var(--app-space-group) 0 6px;
+        color: var(--app-color-text-strong);
+        font-size: var(--app-font-size-body);
+        font-weight: var(--app-font-weight-strong);
+    }
+
+    & h5 {
+        margin: var(--app-space-block) 0 6px;
+        color: var(--app-color-text-muted);
+        font-size: var(--app-font-size-dense);
+        font-weight: var(--app-font-weight-strong);
+    }
+
+    & a {
+        color: var(--app-color-link);
+        text-decoration: none;
+        text-underline-offset: 2px;
+    }
+
+    & a:visited {
+        color: var(--app-color-link-visited);
+    }
+
+    & a:hover {
+        color: var(--app-color-link-hover);
+        text-decoration: underline;
+    }
+
+    & a:focus-visible {
+        border-radius: var(--app-radius-mark);
+        outline: var(--app-outline-focus);
+        outline-offset: var(--app-outline-focus-offset);
+    }
+
+    & strong {
+        color: var(--app-color-text-strong);
+        font-weight: var(--app-font-weight-strong);
+    }
+
+    & ul {
+        margin: 0 0 var(--app-space-stack);
+        padding-left: 20px;
+    }
+
+    & ol {
+        margin: 0 0 var(--app-space-stack);
+        padding-left: 22px;
+    }
+
+    & li {
+        margin-bottom: 4px;
+    }
+
+    & li > ul {
+        margin: 4px 0 0;
+    }
+
+    & li > ol {
+        margin: 4px 0 0;
+    }
+
+    /* JetBrains Mono 합자 비활성 · >=, != 원문 구분 */
+    & code {
+        padding: 1px 3px;
+        border-radius: var(--app-radius-inline);
+        background: var(--app-color-code);
+        color: var(--app-color-text-strong);
+        font-family: var(--app-font-mono);
+        font-size: 1em;
+        font-variant-ligatures: none;
+    }
+
+    /* 코드 블록 · Shiki의 --app-code-* 참조 */
+    & pre {
+        overflow-x: auto;
+        margin: var(--app-space-block) 0;
+        padding: var(--app-space-stack) var(--app-space-block);
+        border: 1px solid var(--app-color-border);
+        border-radius: var(--app-radius-box);
+        background: var(--app-color-code);
+        font-family: var(--app-font-mono);
+        font-size: var(--app-font-size-detail);
+        font-variant-ligatures: none;
+        line-height: var(--app-line-height-code);
+    }
+
+    & pre code {
+        padding: 0;
+        background: none;
+        color: inherit;
+        font-size: inherit;
+    }
+
+    /* 인용과 첫머리 안내 */
+    & blockquote {
+        margin: var(--app-space-block) 0;
+        padding: 0 0 0 var(--app-space-block);
+        border-left: 1px solid var(--app-color-border);
+    }
+
+    & blockquote > :last-child {
+        margin-bottom: 0;
+    }
+
+    & table {
+        width: 100%;
+        border-collapse: collapse;
+        font-size: var(--app-font-size-dense);
+        font-variant-numeric: tabular-nums;
+    }
+
+    & th {
+        padding: var(--app-space-inline) var(--app-space-stack);
+        border-bottom: 1px dotted var(--app-color-border);
+        color: var(--app-color-text-strong);
+        font-weight: var(--app-font-weight-strong);
+        text-align: left;
+        vertical-align: bottom;
+        white-space: nowrap;
+    }
+
+    & td {
+        padding: var(--app-space-inline) var(--app-space-stack);
+        border-bottom: 1px solid var(--app-color-border-soft);
+        text-align: left;
+        vertical-align: top;
+    }
+
+    & tbody tr:last-child td {
+        border-bottom: 0;
+    }
+
+    /* 표의 읽는 행 표시 */
+    & tbody tr:hover td {
+        background: var(--app-color-accent-soft);
+    }
+
+    & hr {
+        margin: var(--app-space-section) 0;
+        border: 0;
+        border-top: 1px dotted var(--app-color-border);
+    }
+    /* stylelint-enable selector-disallowed-list */
+}
+
+/* 공통 문서 머리 · 제목·소개 */
+.wg_prose__head {
+    margin-bottom: var(--app-space-inline);
+    padding-bottom: var(--app-space-block);
+    border-bottom: 1px dotted var(--app-color-border);
+
+    /* stylelint-disable-next-line selector-disallowed-list -- Markdown 생성 머리 */
+    & > :last-child {
+        margin-bottom: 0;
+    }
+
+    /* stylelint-disable selector-disallowed-list -- README의 가운데 정렬 HTML 소개 */
+    & [align="center"] {
+        padding: var(--app-space-group) 0;
+        text-align: center;
+    }
+
+    & [align="center"] > h1 {
+        margin-block: var(--app-space-group);
+        font-size: 24px;
+    }
+
+    & [align="center"] > p {
+        margin-bottom: var(--app-space-block);
+    }
+
+    & [align="center"] > img {
+        width: 72px;
+        image-rendering: pixelated;
+    }
+    /* stylelint-enable selector-disallowed-list */
+}
+
+/* 제목 글자만 강조 · 여러 줄에서도 각 줄을 칠하고 문서 배치는 유지 */
+.wg_prose__headingText {
+    box-decoration-break: clone;
+
+    /* 줄바꿈된 글자 뒤의 바탕은 opacity 레이어로 분리할 수 없어 배경색만 전환 */
+    transition: background-color var(--app-motion-duration-highlight-fade) var(--app-motion-easing-out);
+}
+
+.wg_prose__headingText--highlighted {
+    background-color: var(--app-color-anchor-highlight);
+    transition: none;
+}
+
+/* ::part 가름의 공통 표현 */
+.wg_prose__part {
+    margin-top: var(--app-space-section);
+    padding-top: var(--app-space-stack);
+    border-top: 1px dotted var(--app-color-border);
+    color: var(--app-color-text-strong);
+    font-size: var(--app-font-size-part);
+    font-weight: var(--app-font-weight-strong);
+    line-height: var(--app-line-height-heading);
+    letter-spacing: var(--app-letter-spacing-heading);
+}
+
+/* 넓은 표의 내부 가로 스크롤 */
+.wg_prose__table {
+    overflow-x: auto;
+    margin: var(--app-space-block) 0;
+}
+
+/* 상태 표지 · 확인 초록, 미확인 amber */
+.wg_prose__pill {
+    display: inline-block;
+    padding: 0 5px;
+    border-radius: var(--app-radius-inline);
+    font-size: var(--app-font-size-detail);
+    font-weight: var(--app-font-weight-strong);
+    line-height: 1.6;
+    white-space: nowrap;
+}
+
+.wg_prose__pill--verified {
+    background: var(--app-color-verified-soft);
+    color: var(--app-color-verified);
+}
+
+.wg_prose__pill--unverified {
+    background: var(--app-color-unverified-soft);
+    color: var(--app-color-unverified);
+}
+
+/* 인라인 hex 색 칩 · remark-swatch의 CSS 변수 */
+.wg_prose__color {
+    /* 색 칩과 값 사이 줄바꿈 방지 */
+    white-space: nowrap;
+
+    &::before {
+        display: inline-block;
+        width: 0.8em;
+        height: 0.8em;
+        margin-right: 5px;
+        border: 1px solid var(--app-color-border);
+        border-radius: var(--app-radius-mark);
+        background: var(--wg-prose-chip-color, transparent);
+        content: "";
+        vertical-align: -0.05em;
+    }
+}
+
+/* 빌드 시 생성한 격자 SVG 흐름도 */
+.wg_prose__flow {
+    overflow-x: auto;
+    margin: var(--app-space-block) 0;
+    padding: var(--app-space-block) 0;
+
+    /* stylelint-disable-next-line selector-disallowed-list -- 외부 렌더러 생성 SVG */
+    & svg {
+        display: block;
+        max-width: 100%;
+        height: auto;
+        margin: 0 auto;
+    }
+}
+
+/* 보충 설명 · 본문과 분리되는 제목·왼쪽 선 */
+.wg_prose__note {
+    margin: var(--app-space-block) 0;
+    padding-left: var(--app-space-block);
+    border-left: 2px solid var(--app-color-border);
+
+    & > :last-child {
+        margin-bottom: 0;
+    }
+}
+
+.wg_prose__noteTitle {
+    display: block;
+    margin-bottom: var(--app-space-inline);
+    color: var(--app-color-text-strong);
+    font-weight: var(--app-font-weight-strong);
+}
+
+/* 구현 상세 · 펼침 상태와 marker는 native Details 소유 */
+.wg_prose__details {
+    margin: var(--app-space-block) 0;
+    padding-bottom: var(--app-space-stack);
+    border-top: 1px dotted var(--app-color-border);
+    border-bottom: 1px dotted var(--app-color-border);
+
+    & > :last-child {
+        margin-bottom: 0;
+    }
+}
+
+.wg_prose__detailsSummary {
+    padding: var(--app-space-inline) 0;
+    color: var(--app-color-link);
+    font-weight: var(--app-font-weight-strong);
+    cursor: pointer;
+
+    &:hover {
+        color: var(--app-color-link-hover);
+        text-decoration: underline;
+        text-underline-offset: 2px;
+    }
+
+    &:focus-visible {
+        outline: var(--app-outline-focus);
+        outline-offset: var(--app-outline-focus-offset);
+    }
+}

package/src/component/widget/prose/wg-prose.tsx

@@ -0,0 +1,43 @@
+import clsx from "clsx";
+import "./wg-prose.css";
+
+/**
+ * Markdown HTML과 본문 부품의 공통 표현 입력
+ * remark·rehype 플러그인은 _function 소유
+ */
+export interface WgProseProps {
+    /**
+     * 머리를 포함한 렌더링 완료 HTML
+     */
+    html?: string;
+    /**
+     * README가 없을 때의 안내 머리
+     */
+    head?: {
+        /**
+         * 문서 h1 제목
+         */
+        title: string;
+        /**
+         * 제목 아래 소개 · 선택
+         */
+        lead?: string;
+    };
+}
+
+export const WgProse = (props: WgProseProps) => {
+    if (props.html !== undefined) {
+        return <article className={clsx("wg_prose__root")} dangerouslySetInnerHTML={{__html: props.html}} />;
+    }
+
+    return (
+        <article className={clsx("wg_prose__root")}>
+            {props.head !== undefined && (
+                <header className={clsx("wg_prose__head")}>
+                    <h1>{props.head.title}</h1>
+                    {props.head.lead !== undefined && <p>{props.head.lead}</p>}
+                </header>
+            )}
+        </article>
+    );
+};

package/src/component/widget/shell/_constant/cursor-face.ts

@@ -0,0 +1,9 @@
+/**
+ * 얼굴이 클릭 지점과 겹치지 않는 거리 · 화면 가장자리에도 같은 여백 적용
+ */
+export const cursor_face_offset_px = 16;
+
+/**
+ * 같은 탭의 문서 이동에서 커서 위치를 한 번 이어받는 저장소 키
+ */
+export const cursor_face_storage_key = "fh-cursor-face";

package/src/component/widget/shell/_constant/navigation.ts

@@ -0,0 +1,4 @@
+/**
+ * 모바일 탐색 전환 · wg-shell.css의 폭 조건과 일치
+ */
+export const navigation_mobile_query = "(width < 1024px)";

package/src/component/widget/shell/_constant/reading-line.ts

@@ -0,0 +1,4 @@
+/**
+ * 읽는 선의 반올림 여유 · 경계의 제목을 현재 절에 포함
+ */
+export const reading_line_slack_px = 1;

package/src/component/widget/shell/_function/bind-mobile-navigation.ts

@@ -0,0 +1,140 @@
+import {navigation_mobile_query} from "@/component/widget/shell/_constant/navigation";
+import {revealHashTarget} from "@/util/dom/reveal-hash-target";
+
+/**
+ * 같은 문서 탐색을 데스크톱 사이드바와 모바일 모달 사이에서 이동
+ * 닫기·크기 변경에서 스크롤과 포커스 복원 · 초기화 실패 시 기본 목록 유지
+ */
+export const bindMobileNavigation = () => {
+    const navigation = document.querySelector<HTMLElement>("[data-navigation]");
+    const dialog = document.querySelector<HTMLDialogElement>("[data-navigation-drawer]");
+    const content = document.querySelector<HTMLElement>("[data-navigation-content]");
+    const openButton = document.querySelector<HTMLButtonElement>("[data-navigation-open]");
+    const closeButton = document.querySelector<HTMLButtonElement>("[data-navigation-close]");
+    const sidebar = navigation?.parentElement;
+
+    if (!navigation || !dialog || !content || !openButton || !closeButton || !sidebar) {
+        return;
+    }
+
+    const mobile = matchMedia(navigation_mobile_query);
+
+    /**
+     * Escape 등 네이티브 닫기에서도 배경 스크롤과 버튼의 상태 복원
+     */
+    const handleClose = () => {
+        // 닫기 직후 다시 연 모달에 이전 close 이벤트가 개입하지 않도록 함
+        if (dialog.open) {
+            return;
+        }
+
+        document.body.classList.remove("wg_shell__root--drawerOpen");
+        openButton.setAttribute("aria-expanded", "false");
+    };
+
+    /**
+     * 기본 링크 이동보다 먼저 잠금 해제 · 네이티브 close가 열기 버튼으로 포커스 복원
+     */
+    const closeNavigation = () => {
+        dialog.close();
+        handleClose();
+    };
+
+    /**
+     * 네이티브 모달로 외부 포커스 차단 · 모바일에서만 열기
+     */
+    const handleOpen = () => {
+        if (!mobile.matches || dialog.open) {
+            return;
+        }
+
+        dialog.showModal();
+        document.body.classList.add("wg_shell__root--drawerOpen");
+        openButton.setAttribute("aria-expanded", "true");
+    };
+
+    /**
+     * 대화상자 바깥 배경 클릭만 닫기 · 내부의 빈 공간은 유지
+     */
+    const handleBackdropClick = (event: MouseEvent) => {
+        const bounds = dialog.getBoundingClientRect();
+
+        if (event.target === dialog && (event.clientX < bounds.left || event.clientX > bounds.right || event.clientY < bounds.top || event.clientY > bounds.bottom)) {
+            closeNavigation();
+        }
+    };
+
+    /**
+     * 링크의 기본 이동은 유지 · 목차는 닫은 뒤 실제 제목에 키보드 위치 전달
+     */
+    const handleNavigationClick = (event: MouseEvent) => {
+        if (
+            !dialog.open ||
+            event.defaultPrevented ||
+            event.button !== 0 ||
+            event.metaKey ||
+            event.ctrlKey ||
+            event.shiftKey ||
+            event.altKey ||
+            !(event.target instanceof Element)
+        ) {
+            return;
+        }
+
+        const link = event.target.closest("a[href]");
+
+        if (!(link instanceof HTMLAnchorElement) || (link.target !== "" && link.target !== "_self") || link.hasAttribute("download")) {
+            return;
+        }
+
+        closeNavigation();
+
+        if (link.origin === location.origin && link.pathname === location.pathname && link.search === location.search && link.hash) {
+            const target = revealHashTarget(link.hash);
+
+            if (target) {
+                target.tabIndex = -1;
+                target.focus({preventScroll: true});
+            }
+        }
+    };
+
+    /**
+     * 반응형 전환에도 목록 중복 없음 · 열린 모달을 데스크톱으로 가져가기 전에 닫기
+     */
+    const handleLayoutChange = () => {
+        const focused = document.activeElement;
+
+        if (mobile.matches) {
+            openButton.classList.add("wg_shell__menuToggle--visible");
+            content.append(navigation);
+
+            if (focused instanceof HTMLElement && navigation.contains(focused)) {
+                openButton.focus({preventScroll: true});
+            }
+
+            return;
+        }
+
+        closeNavigation();
+        sidebar.append(navigation);
+
+        if (focused instanceof HTMLElement && navigation.contains(focused)) {
+            focused.focus({preventScroll: true});
+        } else if (focused === openButton || (focused instanceof HTMLElement && dialog.contains(focused))) {
+            sidebar.querySelector<HTMLAnchorElement>(".wg_shell__brand")?.focus({preventScroll: true});
+        }
+
+        // CSS의 폭 조건이 먼저 버튼을 숨겨 포커스가 사라지지 않도록 복원 후 숨김
+        openButton.classList.remove("wg_shell__menuToggle--visible");
+    };
+
+    openButton.addEventListener("click", handleOpen);
+    closeButton.addEventListener("click", closeNavigation);
+    dialog.addEventListener("close", handleClose);
+    dialog.addEventListener("click", handleBackdropClick);
+    navigation.addEventListener("click", handleNavigationClick);
+    mobile.addEventListener("change", handleLayoutChange);
+    handleLayoutChange();
+    sidebar.classList.add("wg_shell__sidebar--navigationReady");
+};