for-humanity 0.1.0

package/src/style/base.css

@@ -0,0 +1,28 @@
+/*
+ * 전역 상자 크기와 스크롤·움직임 기본값
+ */
+
+* {
+    box-sizing: border-box;
+}
+
+/* 페이지 바탕과 절 이동 · 초기 hash 보정 중 smooth scroll 일시 중지 */
+:root {
+    background: var(--app-color-ground);
+    scrollbar-gutter: stable;
+    scroll-behavior: smooth;
+}
+
+/* 움직임 줄이기 · 컴포넌트보다 우선하는 전역 !important 예외 */
+@media (prefers-reduced-motion: reduce) {
+    *,
+    *::before,
+    *::after {
+        animation-duration: 0.01ms !important;
+        animation-delay: 0s !important;
+        animation-iteration-count: 1 !important;
+        transition-duration: 0.01ms !important;
+        transition-delay: 0s !important;
+        scroll-behavior: auto !important;
+    }
+}

package/src/style/token.css

@@ -0,0 +1,162 @@
+/*
+ * 공통 토큰의 단일 출처 · --app-종류-쓰임
+ * 사용 기준: templates/document/design.md · 테마 분기는 color-scheme에 한정
+ * 폭 기준 1024px·640px · 공유 사이드바와 본문 배치
+ */
+
+:root {
+    /* 시스템의 밝게·어둡게 설정을 그대로 따름 */
+    color-scheme: light dark;
+
+    /* 바탕 · ground 페이지, surface 상자, code 코드 */
+    --app-color-ground: light-dark(#fff, #181818);
+    --app-color-surface: light-dark(#fff, #181818);
+    --app-color-code: light-dark(#f1f1eb, #22221f);
+    --app-color-backdrop: light-dark(rgb(0 0 0 / 30%), rgb(0 0 0 / 55%));
+
+    /* 글 · text 본문, strong 강조, muted 라벨 */
+    --app-color-text: light-dark(#333, #d5d5d5);
+    --app-color-text-strong: light-dark(#222, #eee);
+    --app-color-text-muted: light-dark(#666, #aaa);
+
+    /* 앵커로 도착한 제목 · 형광펜 바탕과 테마별 읽기 대비 */
+    --app-color-anchor-highlight: light-dark(#f4f58a, #666322);
+
+    /* 제목 강조 해제 · 움직임 감소는 base.css에서 일괄 차단 */
+    --app-motion-duration-highlight-fade: 600ms;
+    --app-motion-easing-out: ease-out;
+
+    /* 선 · border 상자·목록, soft 표 구분, layout 열 경계 */
+    --app-color-border: light-dark(#aaa, #555);
+    --app-color-border-soft: light-dark(#ddd, #333);
+    --app-color-border-layout: light-dark(#eee, #2b2b2b);
+
+    /* 강조 · 현재 절·코드 · soft 행 hover 바탕 */
+    --app-color-accent: light-dark(#555, #b5b5b5);
+    --app-color-accent-soft: light-dark(#f5f5f2, #222);
+
+    /* 링크 · 기본·방문·hover */
+    --app-color-link: light-dark(#11a, #9db8ff);
+    --app-color-link-visited: light-dark(#51a, #c5a5ed);
+    --app-color-link-hover: light-dark(#44d, #c1d1ff);
+
+    /* 상태 표지 · verified 초록, unverified amber */
+    --app-color-verified: light-dark(#176b36, #82cf95);
+    --app-color-verified-soft: light-dark(#edf5ed, #1d2c20);
+    --app-color-unverified: light-dark(#855700, #dfb26c);
+    --app-color-unverified-soft: light-dark(#faf2df, #30291c);
+
+    /*
+     * 내장 글꼴 · CLI는 @font-face와 자원 URL 생성
+     * 본문·라벨 Pretendard · 코드·흐름도 JetBrains Mono · 사이트 이름 Architects Daughter
+     * 영문 폭 0.6em = 흐름도 12px 격자의 7.2px
+     */
+    --app-font-sans: "Pretendard Variable", system-ui, "Apple SD Gothic Neo", sans-serif;
+    --app-font-mono: "JetBrains Mono Variable", var(--app-font-sans);
+    --app-font-brand: "Architects Daughter", var(--app-font-sans);
+
+    /* 글자 크기 · 12px 기본과 역할별 제목 크기 */
+    --app-font-size-label: 12px;
+    --app-font-size-detail: 12px;
+    --app-font-size-dense: 12px;
+    --app-font-size-body: 12px;
+    --app-font-size-lead: 12px;
+    --app-font-size-part: 13px;
+    --app-font-size-section: 14px;
+    --app-font-size-title: 16px;
+
+    /* 굵기 · 기본 400 · 현재 위치 500 · 제목·강조 600 */
+    --app-font-weight-mark: 400;
+    --app-font-weight-active: 500;
+    --app-font-weight-strong: 600;
+    --app-font-weight-title: 600;
+
+    /* 행간 · 작은 제목·탐색은 1.5, 본문은 한글 획 사이 여유 확보 */
+    --app-line-height-title: 1.5;
+    --app-line-height-heading: 1.5;
+    --app-line-height-tight: 1.5;
+    --app-line-height-code: 1.65;
+    --app-line-height-body: 1.7;
+
+    /* 자간 · 12px 본문·라벨은 기본 폭, 제목만 미세하게 조임 */
+    --app-letter-spacing-label: 0;
+    --app-letter-spacing-brand: 0;
+    --app-letter-spacing-heading: -0.01em;
+    --app-letter-spacing-title: -0.015em;
+
+    /* 공통 간격 · margin·padding·gap의 리듬 · 단독 보정은 지역 값 */
+    --app-space-inline: 6px;
+    --app-space-stack: 10px;
+    --app-space-block: 14px;
+    --app-space-group: 20px;
+    --app-space-section: 32px;
+
+    /* 탐색 트리 · 항목 위아래 여백·묶음 안쪽 여백·가지와 중첩 들여쓰기 */
+    --app-space-tree-row: 2px;
+    --app-space-tree-inset: 4px;
+    --app-space-tree-indent: 12px;
+
+    /* 페이지 틀 · 좁은 화면 값은 아래 @media */
+    --app-space-page-top: 28px;
+    --app-space-gutter: 28px;
+    --app-space-column: 32px;
+    --app-space-sidebar-gap: 32px;
+    --app-size-sidebar: 200px;
+    --app-size-main: 900px;
+    --app-size-page: calc(var(--app-size-main) + (var(--app-size-sidebar) + var(--app-space-sidebar-gap) + var(--app-space-gutter)) * 2);
+    --app-size-brand: calc(var(--app-font-size-title) * var(--app-line-height-title) + var(--app-space-page-top) + var(--app-space-group));
+    --app-size-mobile-header: 56px;
+    --app-size-menu-button: 44px;
+    --app-size-drawer: 320px;
+
+    /* 화면 위쪽 제목 여백 · hash 도착점과 목차 읽는 선의 공통 기준 */
+    --app-space-anchor: 80px;
+
+    /* 모서리 · 직각 기본값 */
+    --app-radius-pill: 0;
+    --app-radius-card: 0;
+    --app-radius-box: 0;
+    --app-radius-inline: 0;
+    --app-radius-mark: 0;
+
+    /* 키보드 포커스 표시 */
+    --app-outline-focus: 2px solid var(--app-color-link);
+    --app-outline-focus-offset: 2px;
+
+    /* 사이드바 사이트 이름 · 커서 장식 */
+    --app-z-index-sticky: 100;
+    --app-z-index-popper: 300;
+
+    /*
+     * Shiki CSS 변수 · 기존 역할색 재사용
+     * 키워드 strong · 함수 accent
+     */
+    --app-code-foreground: var(--app-color-text);
+    --app-code-background: var(--app-color-code);
+    --app-code-token-keyword: var(--app-color-text-strong);
+    --app-code-token-function: var(--app-color-accent);
+    --app-code-token-string: var(--app-color-verified);
+    --app-code-token-string-expression: var(--app-color-verified);
+    --app-code-token-constant: var(--app-color-unverified);
+    --app-code-token-parameter: var(--app-color-text);
+    --app-code-token-comment: var(--app-color-text-muted);
+    --app-code-token-punctuation: var(--app-color-text-muted);
+    --app-code-token-link: var(--app-color-link);
+}
+
+/* 폭 조건 · shell의 breakpoint와 일치 */
+@media (width < 1024px) {
+    :root {
+        --app-space-page-top: 24px;
+        --app-space-gutter: 20px;
+        --app-space-tree-row: 7px;
+        --app-space-anchor: calc(var(--app-size-mobile-header) + var(--app-space-block));
+    }
+}
+
+@media (width < 640px) {
+    :root {
+        --app-space-page-top: 20px;
+        --app-space-gutter: 16px;
+    }
+}

package/src/type/doc-content.ts

@@ -0,0 +1,15 @@
+import type {DocOutline} from "@/component/widget/shell/_type/doc-outline";
+
+/**
+ * README 홈과 일반 문서가 공유하는 렌더링 결과
+ */
+export interface DocContent {
+    /**
+     * 문서 머리와 본문을 포함한 HTML
+     */
+    html: string;
+    /**
+     * 현재 문서의 독립 목차 입력
+     */
+    outline: DocOutline;
+}

package/src/type/doc-data.ts

@@ -0,0 +1,33 @@
+import {z} from "zod";
+import {doc_order_default, doc_type} from "@/constant/doc";
+
+/**
+ * 문서 frontmatter 스키마 · 검증 실패 시 빌드 중단
+ */
+export const docDataSchema = z.object({
+    /**
+     * 문서 이름 · 제목·목록 · 같은 첫 글자 허용
+     */
+    name: z.string().trim().min(1),
+    /**
+     * 짧은 문서 설명 · 사이드바 툴팁
+     */
+    label: z.string(),
+    /**
+     * 문서 종류 · blueprint 전용 표현 미구현
+     */
+    type: z.enum(doc_type).default(doc_type.document),
+    /**
+     * 사이드바의 문서 묶음
+     */
+    group: z.string().trim().min(1),
+    /**
+     * 묶음 안의 읽는 순서 · 미지정 문서는 뒤에서 이름순
+     */
+    order: z.number().int().nonnegative().default(doc_order_default),
+});
+
+/**
+ * 기본값을 적용한 문서 frontmatter
+ */
+export type DocData = z.infer<typeof docDataSchema>;

package/src/type/doc-file-data.ts

@@ -0,0 +1,21 @@
+import type {DocSection} from "@/component/widget/prose/_type/doc-section";
+import type {DocData} from "@/type/doc-data";
+import type {DocHeading} from "@/type/doc-heading";
+
+/**
+ * 문서 처리 중간 계약 · read-docs의 머리말과 rehype의 제목·절 정보
+ */
+export interface DocFileData {
+    /**
+     * 일반 문서의 검증된 머리말 · README 홈은 생략
+     */
+    frontmatter?: DocData;
+    /**
+     * 작성한 제목 · 문서 순서
+     */
+    headings: DocHeading[];
+    /**
+     * 제목별 가름 · headings의 h2·h3 순서와 일치
+     */
+    sections: DocSection[];
+}

package/src/type/doc-heading.ts

@@ -0,0 +1,17 @@
+/**
+ * 제목 하나의 목차 계약 · 문서 순서
+ */
+export interface DocHeading {
+    /**
+     * 제목 깊이 · h1 = 1, h2 = 2
+     */
+    depth: number;
+    /**
+     * 제목 id · URL hash 대상
+     */
+    slug: string;
+    /**
+     * 작성한 제목 텍스트
+     */
+    text: string;
+}

package/src/type/doc.ts

@@ -0,0 +1,16 @@
+import type {DocContent} from "@/type/doc-content";
+import type {DocData} from "@/type/doc-data";
+
+/**
+ * Markdown 파일 하나의 렌더링 결과
+ */
+export interface Doc extends DocContent {
+    /**
+     * 문서 URL id · 확장자 제외 소문자 경로 · 하위 폴더 포함
+     */
+    id: string;
+    /**
+     * 검증된 머리말
+     */
+    data: DocData;
+}

package/src/type/site-assets.ts

@@ -0,0 +1,17 @@
+/**
+ * 모든 페이지가 공유하는 HTML 머리 자원
+ */
+export interface SiteAssets {
+    /**
+     * 내장 @font-face · head의 style 내용
+     */
+    fontCss: string;
+    /**
+     * 선요청 글꼴 URL · 사이트 이름·본문 공통 조각·코드
+     */
+    preload: string[];
+    /**
+     * dev 전용 문서 새로고침 스크립트 포함 여부
+     */
+    reload: boolean;
+}

package/src/type/site-config.ts

@@ -0,0 +1,55 @@
+import {z} from "zod";
+import {copy_error_navigation_clash, copy_site_title_default} from "@/constant/copy";
+import {site_navigation_default} from "@/constant/site";
+import {status_default_phrases, status_kind} from "@/constant/status";
+
+/**
+ * for-humanity.config.mjs 설정 스키마
+ * 명령 시작 시 검증과 기본값 적용 · 앱은 검증 결과만 사용
+ */
+export const siteConfigSchema = z.object({
+    /**
+     * 사이드바 이름과 탭 제목
+     */
+    title: z.string().default(copy_site_title_default),
+    /**
+     * HTML 설명 메타데이터 · 선택
+     */
+    description: z.string().optional(),
+    /**
+     * 탐색 묶음의 읽는 순서 · 미지정 묶음은 뒤에서 이름순
+     */
+    navigation: z
+        .array(z.string().trim().min(1))
+        .refine((groups) => new Set(groups).size === groups.length, copy_error_navigation_clash)
+        .default([...site_navigation_default]),
+    /**
+     * 본문에서 상태 표지로 표시할 문구
+     */
+    status: z
+        .array(
+            z.object({
+                /**
+                 * 찾을 문구 원문
+                 */
+                phrase: z
+                    .string()
+                    .min(1)
+                    .refine((phrase) => phrase.trim().length > 0),
+                /**
+                 * 상태 표지의 색 종류
+                 */
+                kind: z.enum(status_kind),
+                /**
+                 * 문구 뒤의 YYYY-MM-DD 날짜 포함 여부
+                 */
+                date: z.boolean().optional(),
+            }),
+        )
+        .default(status_default_phrases),
+});
+
+/**
+ * 기본값을 적용한 사이트 설정
+ */
+export type SiteConfig = z.infer<typeof siteConfigSchema>;

package/src/type/vfile-data.d.ts

@@ -0,0 +1,10 @@
+import type {DocFileData} from "@/type/doc-file-data";
+
+declare module "vfile" {
+    interface DataMap {
+        /**
+         * 문서 처리 플러그인 간 공유 데이터
+         */
+        fh?: DocFileData;
+    }
+}

package/src/util/dom/find-hash-target.ts

@@ -0,0 +1,18 @@
+/**
+ * URL hash 대상 · 한국어 제목의 percent encoding 해석
+ */
+export const findHashTarget = (hash: string): HTMLElement | null => {
+    if (!hash) {
+        return null;
+    }
+
+    try {
+        return document.getElementById(decodeURIComponent(hash.slice(1)));
+    } catch (error) {
+        if (error instanceof URIError) {
+            return null;
+        }
+
+        throw error;
+    }
+};

package/src/util/dom/reveal-hash-target.ts

@@ -0,0 +1,15 @@
+import {findHashTarget} from "@/util/dom/find-hash-target";
+
+/**
+ * 접힌 내용의 hash 대상과 상위 Details 공개
+ * 초기 접속·문서 안 링크·hash 변경에 동일 적용
+ */
+export const revealHashTarget = (hash: string): HTMLElement | null => {
+    const target = findHashTarget(hash);
+
+    for (let fold = target?.closest("details"); fold; fold = fold.parentElement?.closest("details")) {
+        fold.open = true;
+    }
+
+    return target;
+};

package/src/util/error/to-error-message.ts

@@ -0,0 +1,10 @@
+/**
+ * CLI·dev 공통 오류 문구 · 문법 오류의 파일과 줄 번호 포함
+ */
+export const toErrorMessage = (error: unknown): string => {
+    if (error instanceof Error && "file" in error && typeof error.file === "string" && "line" in error && typeof error.line === "number") {
+        return `${error.file}:${error.line}: ${error.message}`;
+    }
+
+    return error instanceof Error ? error.message : String(error);
+};

package/src/util/font/to-font-css.test.ts

@@ -0,0 +1,41 @@
+import assert from "node:assert/strict";
+import {mkdtempSync, rmSync, writeFileSync} from "node:fs";
+import {tmpdir} from "node:os";
+import {join} from "node:path";
+import {test} from "node:test";
+import {asset_font_dir} from "@/constant/asset";
+import {font_brand_css, font_mono_css, font_sans_css} from "@/constant/font";
+import {toFontCss} from "@/util/font/to-font-css";
+
+test("bundled fonts prevent a late swap after fallback text is visible", () => {
+    for (const css of [font_sans_css, font_mono_css, font_brand_css]) {
+        const result = toFontCss({css: join(process.cwd(), css), fontDir: asset_font_dir});
+
+        assert.match(result.css, /font-display:\s*optional;/);
+        assert.doesNotMatch(result.css, /font-display:\s*swap;/);
+    }
+});
+
+test("font URLs stay stable for unchanged bytes and change when the font changes", (t) => {
+    const root = mkdtempSync(join(tmpdir(), "for-humanity-font-"));
+    const file = join(root, "example.woff2");
+    const css = join(root, "font.css");
+
+    t.after(() => rmSync(root, {recursive: true, force: true}));
+    writeFileSync(css, "@font-face { font-family: Example; font-display: swap; src: url(./example.woff2); }");
+    writeFileSync(file, "first font bytes");
+
+    const first = toFontCss({css, fontDir: asset_font_dir});
+    const repeated = toFontCss({css, fontDir: asset_font_dir});
+
+    assert.deepEqual([...first.files], [...repeated.files]);
+    assert.match(first.css, /example\.[a-f0-9]+\.woff2/);
+    assert.deepEqual([...first.files.values()], [file]);
+
+    writeFileSync(file, "changed font bytes");
+
+    const changed = toFontCss({css, fontDir: asset_font_dir});
+
+    assert.notDeepEqual([...first.files.keys()], [...changed.files.keys()]);
+    assert.notEqual(first.css, changed.css);
+});

package/src/util/font/to-font-css.ts

@@ -0,0 +1,28 @@
+import {createHash} from "node:crypto";
+import {readFileSync} from "node:fs";
+import {basename, dirname, extname, join} from "node:path";
+import {font_display_strategy, font_hash_length} from "@/constant/font";
+
+/**
+ * 내장 @font-face의 표시 정책과 내용 지문 URL 적용 · 원본 파일 수집
+ * 늦은 글꼴 교체와 문서 이동마다 같은 글꼴을 다시 받는 현상 방지
+ */
+export const toFontCss = (options: {css: string; fontDir: string}) => {
+    const files = new Map<string, string>();
+    const css = [...readFileSync(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: string, relativeUrl: string) => {
+                const file = join(dirname(options.css), relativeUrl);
+                const extension = extname(file);
+                const hash = createHash("sha256").update(readFileSync(file)).digest("hex").slice(0, font_hash_length);
+                const url = `${options.fontDir}/${basename(file, extension)}.${hash}${extension}`;
+
+                files.set(url, file);
+
+                return `url(${url})`;
+            }),
+        )
+        .join("\n");
+
+    return {css, files};
+};