for-humanity 0.1.0

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

@@ -0,0 +1,261 @@
+/*
+ * 넓은 화면은 본문 중앙 정렬 · 폭이 줄면 오른쪽 여백부터 축소
+ */
+.wg_shell__root {
+    display: grid;
+    max-width: var(--app-size-page);
+    margin: 0 auto;
+    padding: 0 var(--app-space-gutter);
+    grid-template: "nav main ." 1fr / calc(var(--app-size-sidebar) + var(--app-space-sidebar-gap)) minmax(0, var(--app-size-main)) minmax(0, 1fr);
+    background: var(--app-color-ground);
+    color: var(--app-color-text);
+    font-family: var(--app-font-sans);
+    font-size: var(--app-font-size-body);
+    line-height: var(--app-line-height-body);
+
+    /* 한국어 낱말 단위 줄바꿈 · 긴 식별자만 예외 */
+    word-break: keep-all;
+    overflow-wrap: break-word;
+    text-wrap: pretty;
+    -webkit-font-smoothing: antialiased;
+}
+
+.wg_shell__root--drawerOpen {
+    overflow: hidden;
+}
+
+.wg_shell__brandRow {
+    display: flex;
+
+    /* 공유 사이드바의 스크롤 기준 · 목록과 목차 위에서 이름 고정 */
+    position: sticky;
+    top: 0;
+    z-index: var(--app-z-index-sticky);
+    align-self: start;
+    min-width: 0;
+    height: var(--app-size-brand);
+    padding-block: var(--app-space-page-top) var(--app-space-group);
+    background: var(--app-color-ground);
+    gap: var(--app-space-inline);
+    align-items: start;
+}
+
+.wg_shell__brand {
+    display: block;
+    flex: 1;
+    min-width: 0;
+    overflow: hidden;
+    color: var(--app-color-text-strong);
+    font-family: var(--app-font-brand);
+    font-size: var(--app-font-size-title);
+    font-weight: var(--app-font-weight-mark);
+    line-height: var(--app-line-height-title);
+    letter-spacing: var(--app-letter-spacing-brand);
+    text-decoration: none;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+
+    &:hover {
+        text-decoration: underline;
+    }
+
+    &:focus-visible {
+        /* 브랜드도 hover와 같은 밑줄로 키보드 위치 표시 */
+        outline: none;
+        text-decoration: underline;
+    }
+}
+
+.wg_shell__menuIcon {
+    width: 20px;
+    height: 20px;
+    fill: none;
+    stroke: currentcolor;
+    stroke-linecap: round;
+    stroke-width: 1.5;
+}
+
+.wg_shell__menuToggle {
+    display: none;
+    align-items: center;
+    justify-content: center;
+    flex: none;
+    width: var(--app-size-menu-button);
+    height: var(--app-size-menu-button);
+    padding: 0;
+    border: 0;
+    border-radius: var(--app-radius-box);
+    background: transparent;
+    color: var(--app-color-text-strong);
+    cursor: pointer;
+
+    &:hover {
+        background: var(--app-color-accent-soft);
+    }
+
+    &:focus-visible {
+        outline: var(--app-outline-focus);
+        outline-offset: var(--app-outline-focus-offset);
+    }
+}
+
+.wg_shell__menuToggle--visible {
+    display: flex;
+}
+
+.wg_shell__sidebar {
+    grid-area: nav;
+
+    /* 뷰포트 sticky · 문서 탐색과 목차는 이 컨테이너에서 함께 스크롤 */
+    position: sticky;
+    top: 0;
+    align-self: start;
+    min-width: 0;
+    min-height: 100vh;
+    max-height: 100vh;
+    margin-inline-end: var(--app-space-sidebar-gap);
+    overflow-y: auto;
+    scroll-padding-block: var(--app-size-brand) var(--app-space-block);
+}
+
+.wg_shell__navigation {
+    min-width: 0;
+}
+
+.wg_shell__main {
+    grid-area: main;
+    min-width: 0;
+    max-width: var(--app-size-main);
+    border-inline: 1px solid var(--app-color-border-layout);
+
+    /* 문서 목록의 시작선 · 마지막 절도 읽는 선까지 이동 가능한 끝 여백 */
+    padding-block: var(--app-size-brand) calc(100vh - var(--app-space-anchor));
+    padding-inline: var(--app-space-column);
+}
+
+.wg_shell__drawer {
+    /* 네이티브 모달의 top layer · 뷰포트 왼쪽에 고정 */
+    position: fixed;
+    inset: 0 auto 0 0;
+    width: min(var(--app-size-drawer), calc(100% - var(--app-space-gutter) * 2));
+    max-width: none;
+    height: 100dvh;
+    max-height: 100dvh;
+    margin: 0;
+    padding: 0 var(--app-space-gutter) var(--app-space-group);
+    border: 0;
+    border-right: 1px solid var(--app-color-border-layout);
+    background: var(--app-color-ground);
+    color: var(--app-color-text);
+    overscroll-behavior: contain;
+    scroll-padding-block: var(--app-size-mobile-header) var(--app-space-group);
+
+    &::backdrop {
+        background: var(--app-color-backdrop);
+    }
+}
+
+.wg_shell__drawerHeader {
+    /* 스크롤하는 drawer 안에서 닫기 버튼 유지 */
+    position: sticky;
+    top: 0;
+    z-index: var(--app-z-index-sticky);
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: var(--app-space-inline);
+    min-height: var(--app-size-mobile-header);
+    margin-bottom: var(--app-space-block);
+    background: var(--app-color-ground);
+}
+
+.wg_shell__drawerTitle {
+    margin: 0;
+    font-size: var(--app-font-size-part);
+    font-weight: var(--app-font-weight-strong);
+}
+
+.wg_shell__drawerClose {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    flex: none;
+    width: var(--app-size-menu-button);
+    height: var(--app-size-menu-button);
+    padding: 0;
+    border: 0;
+    border-radius: var(--app-radius-box);
+    background: transparent;
+    color: var(--app-color-text-strong);
+    cursor: pointer;
+
+    &:hover {
+        background: var(--app-color-accent-soft);
+    }
+
+    &:focus-visible {
+        outline: var(--app-outline-focus);
+        outline-offset: var(--app-outline-focus-offset);
+    }
+}
+
+.wg_shell__drawerContent {
+    min-width: 0;
+}
+
+.wg_shell__cursorFace {
+    /* 뷰포트 기준 · 본문 흐름과 포인터 입력에 참여하지 않는 장식 */
+    position: fixed;
+    top: 0;
+    left: 0;
+    z-index: var(--app-z-index-popper);
+    visibility: hidden;
+    pointer-events: none;
+    user-select: none;
+    image-rendering: pixelated;
+}
+
+.wg_shell__cursorFace--visible {
+    visibility: visible;
+}
+
+/* 좁은 화면 · 상단 브랜드와 메뉴 버튼 · 탐색 목록은 네이티브 모달 */
+@media (width < 1024px) {
+    .wg_shell__root {
+        max-width: calc(var(--app-size-main) + var(--app-space-gutter) * 2);
+        grid-template:
+            "nav" auto
+            "main" 1fr / minmax(0, 1fr);
+    }
+
+    .wg_shell__sidebar {
+        position: static;
+        min-height: 0;
+        max-height: none;
+        overflow-y: visible;
+        margin-block-end: var(--app-space-block);
+        margin-inline-end: 0;
+        border-bottom: 1px solid var(--app-color-border-layout);
+    }
+
+    .wg_shell__sidebar--navigationReady {
+        /* 본문을 스크롤해도 메뉴 진입 유지 · 스크립트 없는 긴 목록에는 적용하지 않음 */
+        position: sticky;
+        top: 0;
+        z-index: var(--app-z-index-sticky);
+        background: var(--app-color-ground);
+    }
+
+    .wg_shell__brandRow {
+        position: static;
+        height: var(--app-size-mobile-header);
+        padding-block: 0;
+        align-items: center;
+    }
+
+    .wg_shell__main {
+        padding-block-start: var(--app-space-page-top);
+        padding-inline: 0;
+        border-inline: 0;
+    }
+}

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

@@ -0,0 +1,147 @@
+import clsx from "clsx";
+import type {ReactNode} from "react";
+import {toTocGroups} from "@/component/widget/shell/_function/to-toc-groups";
+import type {DocOutline} from "@/component/widget/shell/_type/doc-outline";
+import {WgShellNav} from "@/component/widget/shell/_wg-shell-nav";
+import {WgShellToc} from "@/component/widget/shell/_wg-shell-toc";
+import {asset_client_path, asset_favicon_path, asset_reload_path, asset_style_path} from "@/constant/asset";
+import {copy_nav_close, copy_nav_open, copy_nav_title} from "@/constant/copy";
+import type {Doc} from "@/type/doc";
+import type {SiteAssets} from "@/type/site-assets";
+import type {SiteConfig} from "@/type/site-config";
+import "@/style/base.css";
+import "@/style/token.css";
+import "./wg-shell.css";
+
+/**
+ * dev 문서 변경 시 SSE 새로고침
+ */
+const reloadScript = `new EventSource(${JSON.stringify(asset_reload_path)}).onmessage=function(){location.reload()}`;
+
+/**
+ * 공통 HTML 틀의 입력 · 문서 탐색·현재 목차·본문
+ */
+export interface WgShellProps {
+    /**
+     * 사이트 이름 · 탭과 사이드바
+     */
+    site: SiteConfig;
+    /**
+     * 사이드바 전체 문서 목록
+     */
+    docs: Doc[];
+    /**
+     * HTML 머리의 글꼴·dev 스크립트
+     */
+    assets: SiteAssets;
+    /**
+     * 탭 제목의 문서 이름 · 첫 화면 생략
+     */
+    title?: string;
+    /**
+     * 현재 문서 id · 첫 화면 생략
+     */
+    current?: string;
+    /**
+     * 현재 문서 또는 README 홈의 목차
+     */
+    outline?: DocOutline;
+    /**
+     * 현재 페이지 본문
+     */
+    children: ReactNode;
+}
+
+export const WgShell = (props: WgShellProps) => {
+    const tocGroups = props.outline === undefined ? [] : toTocGroups(props.outline);
+
+    return (
+        <html lang="ko">
+            {/**
+             * 공통 자원 · 초기 smooth scroll은 client.ts의 hash 위치 보정 후 복원
+             */}
+            <head>
+                <meta charSet="utf-8" />
+                <meta name="viewport" content="width=device-width, initial-scale=1" />
+                {props.site.description !== undefined && <meta name="description" content={props.site.description} />}
+                <title>{props.title === undefined ? props.site.title : `${props.title} · ${props.site.title}`}</title>
+                <link rel="icon" href={asset_favicon_path} type="image/svg+xml" />
+                <style dangerouslySetInnerHTML={{__html: props.assets.fontCss}} />
+                {props.assets.preload.map((href) => (
+                    <link key={href} rel="preload" href={href} as="font" type="font/woff2" crossOrigin="" />
+                ))}
+                <script dangerouslySetInnerHTML={{__html: 'document.documentElement.style.scrollBehavior="auto"'}} />
+                <link rel="stylesheet" href={asset_style_path} />
+                {props.assets.reload && <script dangerouslySetInnerHTML={{__html: reloadScript}} />}
+            </head>
+            {/**
+             * 문서 탐색·현재 목차·본문 · 브라우저 동작 연결
+             */}
+            <body className={clsx("wg_shell__root")}>
+                {/**
+                 * 데스크톱의 공유 사이드바 · 모바일에서는 브랜드와 메뉴 버튼
+                 */}
+                <div className={clsx("wg_shell__sidebar")}>
+                    {/**
+                     * 브랜드와 모바일 메뉴 진입 · 버튼은 동작 연결 후 표시
+                     */}
+                    <div className={clsx("wg_shell__brandRow")}>
+                        {/**
+                         * 어느 문서에서도 README 홈으로 이동
+                         */}
+                        <a className={clsx("wg_shell__brand")} href="/" aria-current={props.current === undefined ? "page" : undefined}>
+                            {props.site.title}
+                        </a>
+                        {/**
+                         * 접힌 모바일 탐색의 진입점과 열림 상태 전달
+                         */}
+                        <button
+                            className={clsx("wg_shell__menuToggle")}
+                            type="button"
+                            aria-label={copy_nav_open}
+                            aria-controls="fh-navigation-drawer"
+                            aria-expanded="false"
+                            data-navigation-open=""
+                        >
+                            <svg className={clsx("wg_shell__menuIcon")} viewBox="0 0 24 24" aria-hidden="true" focusable="false">
+                                <path d="M4 6h16M4 12h16M4 18h16" />
+                            </svg>
+                        </button>
+                    </div>
+                    {/**
+                     * 같은 탐색 DOM을 모바일 대화상자로 이동 · 스크립트 없이도 기본 목록 제공
+                     */}
+                    <div className={clsx("wg_shell__navigation")} data-navigation="">
+                        <WgShellNav site={props.site} docs={props.docs} current={props.current} />
+                        {tocGroups.length > 0 && <WgShellToc groups={tocGroups} />}
+                    </div>
+                </div>
+                <main className={clsx("wg_shell__main")}>{props.children}</main>
+                {/**
+                 * 브라우저의 모달 포커스·Escape 처리 · 목록은 한 번만 렌더링
+                 */}
+                <dialog className={clsx("wg_shell__drawer")} id="fh-navigation-drawer" aria-labelledby="fh-navigation-title" data-navigation-drawer="">
+                    <div className={clsx("wg_shell__drawerHeader")}>
+                        {/**
+                         * 대화상자의 접근 가능한 이름
+                         */}
+                        <h2 className={clsx("wg_shell__drawerTitle")} id="fh-navigation-title">
+                            {copy_nav_title}
+                        </h2>
+                        {/**
+                         * 목록을 스크롤해도 보이는 닫기 동작
+                         */}
+                        <button className={clsx("wg_shell__drawerClose")} type="button" aria-label={copy_nav_close} data-navigation-close="">
+                            <svg className={clsx("wg_shell__menuIcon")} viewBox="0 0 24 24" aria-hidden="true" focusable="false">
+                                <path d="m6 6 12 12M18 6 6 18" />
+                            </svg>
+                        </button>
+                    </div>
+                    <div className={clsx("wg_shell__drawerContent")} data-navigation-content="" />
+                </dialog>
+                <img className={clsx("wg_shell__cursorFace")} src={asset_favicon_path} width="24" height="24" alt="" aria-hidden="true" draggable={false} data-cursor-face="" />
+                <script type="module" src={asset_client_path} />
+            </body>
+        </html>
+    );
+};

package/src/constant/asset.ts

@@ -0,0 +1,48 @@
+/*
+ * 정적 빌드와 dev의 공통 자원 URL
+ */
+
+/**
+ * 문서 경로와 구분한 자원 폴더
+ */
+export const asset_dir = "_fh";
+
+/**
+ * esbuild의 컴포넌트 CSS 묶음
+ */
+export const asset_style_path = `/${asset_dir}/style.css`;
+
+/**
+ * 테마·목차·hash 보정 브라우저 스크립트
+ */
+export const asset_client_path = `/${asset_dir}/client.js`;
+
+/**
+ * 자체 호스팅 글꼴 폴더
+ */
+export const asset_font_dir = `/${asset_dir}/fonts`;
+
+/**
+ * dev 문서 변경 알림 SSE URL
+ */
+export const asset_reload_path = `/${asset_dir}/reload`;
+
+/**
+ * 탭 아이콘 URL
+ */
+export const asset_favicon_path = "/favicon.svg";
+
+/**
+ * dev 자원 응답의 확장자별 content-type
+ */
+export const asset_content_types: Record<string, string> = {
+    ".css": "text/css; charset=utf-8",
+    ".js": "text/javascript; charset=utf-8",
+    ".woff2": "font/woff2",
+    ".svg": "image/svg+xml",
+};
+
+/**
+ * 미등록 확장자의 content-type
+ */
+export const asset_content_type_default = "application/octet-stream";

package/src/constant/cli.ts

@@ -0,0 +1,19 @@
+/**
+ * 명령 생략 시 dev
+ */
+export const cli_default_command = "dev";
+
+/**
+ * 문서 폴더 생략 시 현재 폴더
+ */
+export const cli_default_docs_dir = ".";
+
+/**
+ * 문서 폴더의 선택 설정 파일
+ */
+export const cli_config_file_name = "for-humanity.config.mjs";
+
+/**
+ * dev·preview 공통 포트
+ */
+export const cli_dev_port = 4321;

package/src/constant/copy.ts

@@ -0,0 +1,108 @@
+/*
+ * 화면·CLI 공통 문구 · 번역 분리의 단일 출처
+ */
+
+/**
+ * 사이트 제목의 기본값 · 사이드바와 탭
+ */
+export const copy_site_title_default = "for humanity";
+
+/**
+ * 사이드바의 접근 가능한 이름
+ */
+export const copy_nav_aria_label = "Document navigation";
+
+/**
+ * 모바일 문서 탐색 열기 버튼
+ */
+export const copy_nav_open = "Open navigation";
+
+/**
+ * 모바일 문서 탐색 닫기 버튼
+ */
+export const copy_nav_close = "Close navigation";
+
+/**
+ * 모바일 문서 탐색 대화상자 제목
+ */
+export const copy_nav_title = "Navigation";
+
+/**
+ * README가 없는 홈의 안내
+ */
+export const copy_home_missing = "문서 폴더에 README.md를 추가하면 이곳에 홈 화면으로 표시됩니다.";
+
+/**
+ * 현재 문서 목차 라벨
+ */
+export const copy_nav_toc_label = "Contents";
+
+/**
+ * 대소문자만 다른 README 중복 오류
+ */
+export const copy_error_home_clash = "홈 README가 겹친다";
+
+/**
+ * CLI 오류 접두사
+ */
+export const copy_error_prefix = "for-humanity";
+
+/**
+ * 내장 본문 글꼴의 공통 조각이 누락된 패키지 오류
+ */
+export const copy_error_font_preload = "Missing bundled font for preload";
+
+/**
+ * 미지원 명령 오류
+ */
+export const copy_error_unknown_command = "모르는 명령이다";
+
+/**
+ * 설정 검증 오류 · 항목 경로와 이유 추가
+ */
+export const copy_error_config = "설정이 틀렸다";
+
+/**
+ * 문서 frontmatter 오류 · 파일과 항목 추가
+ */
+export const copy_error_frontmatter = "frontmatter가 올바르지 않다";
+
+/**
+ * 탐색 순서에 같은 묶음을 두 번 지정한 설정 오류
+ */
+export const copy_error_navigation_clash = "navigation의 묶음이 겹친다";
+
+/**
+ * 빈 id·예약 경로·URL 예약 문자 오류
+ */
+export const copy_error_doc_id = "문서 id에 사용할 수 없는 경로";
+
+/**
+ * 확장자·대소문자 정규화 후 문서 경로 중복
+ */
+export const copy_error_doc_id_clash = "문서 id가 겹친다";
+
+/**
+ * 흐름도 렌더링 실패
+ */
+export const copy_error_flow = "흐름도를 그리지 못했다";
+
+/**
+ * 미지원 블록 지시문 오류
+ */
+export const copy_error_unknown_directive = "모르는 부품이다";
+
+/**
+ * 부품의 작성 계약 오류 · 이름과 수정 기준 추가
+ */
+export const copy_error_directive_syntax = "부품 문법이 올바르지 않다";
+
+/**
+ * 없는 Markdown 링크 경고 · 빌드 계속
+ */
+export const copy_warn_broken_link = "없는 문서로 건 링크다";
+
+/**
+ * 미등록 날짜 상태 문구 경고
+ */
+export const copy_warn_unknown_status = "설정에 없는 상태 문구다";

package/src/constant/doc.ts

@@ -0,0 +1,13 @@
+/**
+ * 문서 종류 · document 글 정리, blueprint 화면 설계
+ * blueprint 전용 표현 미구현
+ */
+export const doc_type = {
+    document: "document",
+    blueprint: "blueprint",
+} as const;
+
+/**
+ * 순서 미지정 문서는 번호가 있는 문서 뒤에서 이름순 배치
+ */
+export const doc_order_default = Number.MAX_SAFE_INTEGER;

package/src/constant/font.ts

@@ -0,0 +1,39 @@
+/*
+ * 패키지 내장 글꼴 · OFL 라이선스는 각 폴더
+ * CLI에서 @font-face와 자원 생성 · font-family는 token.css 소유
+ */
+
+/**
+ * 본문 글꼴 CSS · 패키지 기준 경로 · dynamic subset 92개
+ */
+export const font_sans_css = "src/asset/font/pretendard/pretendardvariable-dynamic-subset.css";
+
+/**
+ * 코드 글꼴 CSS · 라틴 subset · 한글은 본문 글꼴
+ */
+export const font_mono_css = "src/asset/font/jetbrains-mono/jetbrains-mono.css";
+
+/**
+ * 사이트 이름 글꼴 CSS · Architects Daughter Regular · 라틴 subset
+ */
+export const font_brand_css = "src/asset/font/architects-daughter/architects-daughter.css";
+
+/**
+ * 탐색·라틴 문자에 필요한 본문 조각 · 92개 전체 선요청 방지
+ */
+export const font_sans_preload_file = "PretendardVariable.subset.91.woff2";
+
+/**
+ * 늦게 받은 글꼴로 이미 보이는 대체 글꼴을 교체하지 않는 표시 정책
+ */
+export const font_display_strategy = "optional";
+
+/**
+ * 글꼴 파일 내용의 URL 지문 길이 · 파일 변경 시 이전 캐시와 분리
+ */
+export const font_hash_length = 12;
+
+/**
+ * 내용 지문이 붙은 글꼴만 장기 재사용 · CSS와 브라우저 스크립트는 대상 제외
+ */
+export const font_cache_control = "public, max-age=31536000, immutable";

package/src/constant/locale.ts

@@ -0,0 +1,9 @@
+/**
+ * 영어 문서 이름의 정렬 locale
+ */
+export const locale_doc_name = "en";
+
+/**
+ * 한국어 문서 묶음의 정렬 locale
+ */
+export const locale_doc_group = "ko";

package/src/constant/site.ts

@@ -0,0 +1,9 @@
+/**
+ * 설정 파일 부재 시 입력 · 스키마 기본값 적용
+ */
+export const site_config_absent = {};
+
+/**
+ * 탐색 순서 생략 시 모든 묶음을 이름순 배치
+ */
+export const site_navigation_default: readonly string[] = [];

package/src/constant/status.ts

@@ -0,0 +1,15 @@
+/**
+ * 상태 표지 종류 · verified 초록, unverified amber
+ */
+export const status_kind = {
+    verified: "verified",
+    unverified: "unverified",
+} as const;
+
+/**
+ * 기본 상태 문구 · 확인됨은 뒤의 날짜 포함
+ */
+export const status_default_phrases = [
+    {phrase: "확인됨", kind: status_kind.verified, date: true},
+    {phrase: "확인되지 않았다", kind: status_kind.unverified},
+];