for-humanity 0.4.3 → 0.5.0

package/package.json

@@ -1,18 +1,17 @@
 {
     "name": "for-humanity",
-    "version": "0.4.3",
-    "description": "Documents written for humans to read: a docs kit with a sidebar, parts, sections and flowcharts, built on Hono and React",
+    "version": "0.5.0",
+    "description": "Documents written for humans to read: a docs kit with a sidebar, parts, sections and flowcharts, built on Hono JSX",
     "keywords": [
         "docs",
         "documentation",
         "hono",
-        "react",
         "markdown",
         "mermaid",
         "korean"
     ],
     "license": "MIT",
-    "author": "하민우",
+    "author": "\ud558\ubbfc\uc6b0",
     "repository": {
         "type": "git",
         "url": "git+https://github.com/minu-ha/for-humanity.git"
@@ -34,14 +33,15 @@
         "node": ">=22"
     },
     "scripts": {
-        "build:kit": "esbuild src/cli.ts --bundle --platform=node --format=esm --packages=external --jsx=automatic --outfile=dist/cli.js && esbuild src/client.ts --bundle --platform=browser --format=esm --jsx=automatic --minify --define:process.env.NODE_ENV='\"production\"' --outdir=dist",
+        "build:kit": "node script/build-kit.mjs",
         "sync:readme": "node util/sync-readme.mjs",
         "sync:docs": "pnpm sync:readme && node util/sync-changelog.mjs",
         "dev": "pnpm sync:docs && pnpm build:kit && node dist/cli.js dev templates/document",
         "build": "pnpm sync:docs && pnpm build:kit && node dist/cli.js build templates/document",
         "build:pages": "pnpm build && node util/prepare-pages.mjs",
         "preview": "node dist/cli.js preview templates/document",
-        "test": "esbuild src/util/async/to-change-queue.test.ts src/util/font/to-font-css.test.ts src/content/read-docs.test.ts --bundle --platform=node --format=esm --packages=external --outbase=src --outdir=node_modules/.cache/for-humanity-tests --out-extension:.js=.mjs && node --test node_modules/.cache/for-humanity-tests/util/async/*.test.mjs node_modules/.cache/for-humanity-tests/content/*.test.mjs node_modules/.cache/for-humanity-tests/util/font/*.test.mjs util/*.test.mjs",
+        "test": "node script/test.mjs",
+        "test:navigation": "pnpm build:kit && node util/navigation/check-navigation.test.mjs",
         "lint": "biome check && stylelint \"src/**/*.css\"",
         "lint:fix": "biome check --write && stylelint \"src/**/*.css\" --fix",
         "typecheck": "tsc --noEmit",
@@ -59,8 +59,6 @@
         "hono": "^4.13.12",
         "mdast-util-find-and-replace": "^3.0.2",
         "mdast-util-to-string": "^4.0.0",
-        "react": "^19.3.0",
-        "react-dom": "^19.3.0",
         "rehype-raw": "^7.0.0",
         "rehype-stringify": "^10.0.1",
         "remark-directive": "^4.0.0",
@@ -74,15 +72,14 @@
         "unist-util-visit": "^5.1.0",
         "vfile": "^6.0.3",
         "yaml": "^2.9.1",
-        "zod": "^4.6.5"
+        "zod": "^4.6.5",
+        "zustand": "^5.0.15"
     },
     "devDependencies": {
         "@biomejs/biome": "^2.5.14",
         "@types/hast": "^3.0.5",
         "@types/mdast": "^4.0.4",
         "@types/node": "^26.6.3",
-        "@types/react": "^19.3.0",
-        "@types/react-dom": "^19.3.0",
         "esbuild": "^0.28.2",
         "mdast-util-to-hast": "^13.2.1",
         "playwright": "^1.63.0",

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

@@ -3,6 +3,11 @@
  */
 export const cursor_face_offset_px = 16;
 
+/**
+ * 포인터 얼굴의 고정 표시 크기 · 좌표 계산과 SSR에서 같은 값 사용
+ */
+export const cursor_face_size_px = 24;
+
 /**
  * 같은 탭의 문서 이동에서 커서 위치를 한 번 이어받는 저장소 키
  */

package/src/component/widget/cursor-face/wg-cursor-face.css

@@ -0,0 +1,15 @@
+.wg_cursorFace__root {
+    /* 뷰포트 기준 · 본문 흐름과 포인터 입력에 참여하지 않는 장식 */
+    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_cursorFace__root--visible {
+    visibility: visible;
+}

package/src/component/widget/cursor-face/wg-cursor-face.tsx

@@ -0,0 +1,153 @@
+import clsx from "clsx";
+import {useLayoutEffect, useRef} from "hono/jsx";
+import {cursor_face_offset_px, cursor_face_size_px, cursor_face_storage_key} from "@/component/widget/cursor-face/_constant/cursor-face";
+import {asset_favicon_path} from "@/constant/asset";
+import "./wg-cursor-face.css";
+
+/**
+ * SSR 기본 장식과 브라우저 DOM 연결을 구분하는 입력
+ */
+export interface WgCursorFaceProps {
+    /**
+     * 브라우저 셸이 준비한 DOM ref·이벤트 연결 활성화
+     */
+    ready: boolean;
+}
+
+export const WgCursorFace = (props: WgCursorFaceProps) => {
+    const faceRef = useRef<HTMLImageElement | null>(null);
+    const mediaRef = useRef<MediaQueryList | null>(null);
+    const positionRef = useRef({x: 0, y: 0, frame: 0});
+
+    /**
+     * 화면 이탈·터치 전환에서 예약된 이동까지 취소
+     */
+    const handleCursorHide = () => {
+        cancelAnimationFrame(positionRef.current.frame);
+        positionRef.current.frame = 0;
+        faceRef.current?.classList.remove("wg_cursorFace__root--visible");
+    };
+
+    /**
+     * 비활성 전환에서만 숨겨 새 마우스 이동을 취소하지 않음
+     */
+    const handleCursorMediaChange = () => {
+        if (!mediaRef.current?.matches) handleCursorHide();
+    };
+
+    /**
+     * 화면 갱신마다 한 번만 반영 · transform으로 본문 재배치 방지
+     */
+    const renderCursorFace = () => {
+        if (positionRef.current.frame !== 0) return;
+        positionRef.current.frame = requestAnimationFrame(() => {
+            positionRef.current.frame = 0;
+            const face = faceRef.current;
+            if (face === null) return;
+            face.style.transform = `translate3d(
+                ${Math.max(0, Math.min(positionRef.current.x + cursor_face_offset_px, document.documentElement.clientWidth - face.width - cursor_face_offset_px))}px,
+                ${Math.max(0, Math.min(positionRef.current.y + cursor_face_offset_px, document.documentElement.clientHeight - face.height - cursor_face_offset_px))}px,
+                0
+            )`;
+            face.classList.add("wg_cursorFace__root--visible");
+        });
+    };
+
+    /**
+     * 클릭·텍스트 선택 중에도 장식 유지 · 실제 마우스 입력만 좌표 반영
+     */
+    const handleDocumentPointer = (event: PointerEvent) => {
+        if (!mediaRef.current?.matches || event.pointerType !== "mouse") {
+            handleCursorHide();
+            return;
+        }
+        positionRef.current.x = event.clientX;
+        positionRef.current.y = event.clientY;
+        renderCursorFace();
+    };
+
+    /**
+     * 새 마우스 이동 없이 화면 가장자리의 좌표 재계산
+     */
+    const handleCursorResize = () => {
+        if (faceRef.current?.classList.contains("wg_cursorFace__root--visible")) renderCursorFace();
+    };
+
+    /**
+     * 같은 탭의 문서 이동에서 마지막 좌표를 전달 · 저장 실패는 장식에만 영향
+     */
+    const handlePageHide = () => {
+        if (!faceRef.current?.classList.contains("wg_cursorFace__root--visible")) return;
+        try {
+            sessionStorage.setItem(cursor_face_storage_key, JSON.stringify({x: positionRef.current.x, y: positionRef.current.y}));
+        } catch {
+            // 저장소 차단 시 현재 페이지의 포인터 동작 유지
+        }
+    };
+
+    /**
+     * 첫 진입·BFCache 복귀의 좌표를 한 번 소비 · 외부 저장 값은 검증 후 사용
+     */
+    const handlePageShow = () => {
+        try {
+            const stored = sessionStorage.getItem(cursor_face_storage_key);
+            sessionStorage.removeItem(cursor_face_storage_key);
+            if (stored === null || !mediaRef.current?.matches) return;
+            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)
+            ) {
+                positionRef.current.x = point.x;
+                positionRef.current.y = point.y;
+                renderCursorFace();
+            }
+        } catch {
+            // 손상된 좌표는 다음 실제 마우스 입력으로 복구
+        }
+    };
+
+    /**
+     * 첫 paint 전 좌표 복원 · 해제 시 전역 이벤트와 예약 frame을 함께 정리
+     */
+    useLayoutEffect(() => {
+        if (!props.ready) return;
+        const lifetime = new AbortController();
+        const media = matchMedia("(hover: hover) and (pointer: fine) and (prefers-reduced-motion: no-preference)");
+        mediaRef.current = media;
+        handlePageShow();
+        document.addEventListener("pointermove", handleDocumentPointer, {passive: true, signal: lifetime.signal});
+        document.addEventListener("pointerdown", handleDocumentPointer, {passive: true, signal: lifetime.signal});
+        document.documentElement.addEventListener("pointerleave", handleCursorHide, {signal: lifetime.signal});
+        addEventListener("blur", handleCursorHide, {signal: lifetime.signal});
+        addEventListener("resize", handleCursorResize, {signal: lifetime.signal});
+        addEventListener("pagehide", handlePageHide, {signal: lifetime.signal});
+        addEventListener("pageshow", handlePageShow, {signal: lifetime.signal});
+        media.addEventListener("change", handleCursorMediaChange, {signal: lifetime.signal});
+        return () => {
+            lifetime.abort();
+            mediaRef.current = null;
+            handleCursorHide();
+        };
+    }, [props.ready]);
+
+    return (
+        <img
+            ref={props.ready ? faceRef : undefined}
+            className={clsx("wg_cursorFace__root")}
+            src={asset_favicon_path}
+            width={cursor_face_size_px}
+            height={cursor_face_size_px}
+            alt=""
+            aria-hidden="true"
+            draggable={false}
+            data-cursor-face=""
+        />
+    );
+};

package/src/component/widget/navigation/_constant/navigation-data-schema.ts

@@ -0,0 +1,35 @@
+import {array, boolean, lazy, minLength, number, object, optional, string, type ZodMiniType} from "zod/mini";
+import type {NavigationData, NavigationDoc, NavigationGroup} from "@/component/widget/navigation/_type/navigation-data";
+
+const navigationDocSchema: ZodMiniType<NavigationDoc> = object({
+    id: string(),
+    name: string(),
+    label: string(),
+    active: boolean(),
+    current: boolean(),
+    children: lazy(() => array(navigationDocSchema)),
+});
+const navigationGroupSchema: ZodMiniType<NavigationGroup> = object({
+    name: string(),
+    path: array(string()),
+    current: boolean(),
+    docs: array(navigationDocSchema),
+    groups: lazy(() => array(navigationGroupSchema)),
+});
+const headingSchema = object({depth: number(), slug: string(), text: string()});
+
+/**
+ * HTML에 포함된 JSON을 읽는 브라우저 경계 · 손상된 자료에는 서버 HTML 유지
+ */
+export const navigationDataSchema: ZodMiniType<NavigationData> = object({
+    title: string(),
+    groups: array(navigationGroupSchema),
+    outline: array(
+        object({
+            part: optional(string()),
+            sections: array(object({heading: headingSchema, part: optional(string()), subs: array(object({heading: headingSchema}))})).check(minLength(1)),
+        }),
+    ),
+    pageId: string(),
+    home: boolean(),
+});

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

@@ -0,0 +1,9 @@
+/**
+ * 모바일 탐색 전환 · wg-shell.css의 폭 조건과 일치
+ */
+export const navigation_mobile_query = "(width < 1024px)";
+
+/**
+ * 양쪽 240px 탐색·본문 900px·간격 120px와 스크롤바가 들어가는 3열 기준
+ */
+export const navigation_wide_query = "(width >= 1536px)";

package/src/component/widget/navigation/_function/restore-navigation-scroll.ts

@@ -0,0 +1,59 @@
+import type {NavigationLayout} from "@/store/navigation/navigation-state";
+import type {toNavigationScrollState} from "@/store/navigation/to-navigation-scroll-state";
+
+/**
+ * 초기 HTML과 저장 스토어가 같은 좌표 형태를 소비하는 복원 경계
+ */
+interface RestoreNavigationScrollOptions {
+    /**
+     * persist 키 · 이전 배치별 키의 접두사도 동일
+     */
+    key: string;
+    /**
+     * 수용할 저장 형태 버전
+     */
+    version: number;
+    /**
+     * 현재 표시 중인 화면 배치
+     */
+    layout: NavigationLayout;
+    /**
+     * persist와 같은 저장 자료 검증
+     */
+    toState: typeof toNavigationScrollState;
+}
+
+/**
+ * 탐색 진입점에서 첫 paint 전 복원 · 기존 배치별 저장 자료도 한 번 수용
+ */
+export const restoreNavigationScroll = (options: RestoreNavigationScrollOptions) => {
+    const navigation = document.querySelector<HTMLElement>("[data-navigation]");
+    const documents = document.querySelector<HTMLElement>('[data-navigation-scroll="documents"]');
+    const outline = document.querySelector<HTMLElement>('[data-navigation-scroll="outline"]');
+    if (!navigation || !documents || !outline) return;
+    // module을 기다리는 동안 breakpoint가 바뀌었는지 구분 · 자료가 없어도 적용 배치는 기록
+    navigation.dataset.navigationLayout = options.layout;
+
+    try {
+        const value = sessionStorage.getItem(options.key);
+        const stored: unknown = value === null ? undefined : JSON.parse(value);
+        const state =
+            typeof stored === "object" && stored !== null && "version" in stored && stored.version === options.version && "state" in stored
+                ? options.toState(stored.state)
+                : {positions: {}};
+        const legacy = sessionStorage.getItem(`${options.key}:${options.layout === "drawer" ? "drawer" : "desktop"}`);
+        const previous =
+            state.positions[options.layout] === undefined && legacy !== null
+                ? options.toState({positions: {[options.layout]: JSON.parse(legacy)}}).positions[options.layout]
+                : undefined;
+        const position = state.positions[options.layout] ?? previous;
+        const signature = [...navigation.querySelectorAll<HTMLAnchorElement>(".wg_navigationNav__root a[href]")].map((link) => `${link.pathname}:${link.textContent}`).join("\n");
+        if (position === undefined || position.navigation !== signature) return;
+
+        documents.scrollTop = position.documents;
+        // 공통 문서 목록은 페이지 간 공유 · 목차는 같은 페이지에서만 재사용
+        if (position.pathname === location.pathname) outline.scrollTop = position.outline;
+    } catch {
+        // 차단·손상된 저장소는 복원만 생략 · 기본 링크와 스크롤 유지
+    }
+};

package/src/{content → component/widget/navigation/_function}/to-doc-groups/_to-doc-branches.ts

@@ -1,6 +1,6 @@
-import {locale_doc_name} from "@/constant/locale";
+import {locale_doc_name} from "@/component/widget/navigation/_constant/locale";
+import type {DocBranch} from "@/component/widget/navigation/_type/doc-branch";
 import type {Doc} from "@/type/doc";
-import type {DocBranch} from "@/type/doc-branch";
 
 /**
  * 검증된 부모 관계로 문서 가지를 재귀 구성 · 형제 순서와 URL 유지

package/src/{content → component/widget/navigation/_function}/to-doc-groups/_to-doc-group-branches.ts

@@ -1,7 +1,7 @@
-import {locale_doc_group} from "@/constant/locale";
-import {toDocBranches} from "@/content/to-doc-groups/_to-doc-branches";
+import {locale_doc_group} from "@/component/widget/navigation/_constant/locale";
+import {toDocBranches} from "@/component/widget/navigation/_function/to-doc-groups/_to-doc-branches";
+import type {DocGroup} from "@/component/widget/navigation/_type/doc-group";
 import type {Doc} from "@/type/doc";
-import type {DocGroup} from "@/type/doc-group";
 
 /**
  * 같은 부모의 문서를 다음 경로 단계로 묶는 재귀 입력

package/src/{content → component/widget/navigation/_function}/to-doc-groups/to-doc-groups.ts

@@ -1,4 +1,4 @@
-import {toDocGroupBranches} from "@/content/to-doc-groups/_to-doc-group-branches";
+import {toDocGroupBranches} from "@/component/widget/navigation/_function/to-doc-groups/_to-doc-group-branches";
 import type {Doc} from "@/type/doc";
 import type {SiteConfig} from "@/type/site-config";
 

package/src/component/widget/navigation/_function/to-navigation-branch-id.ts

@@ -0,0 +1,6 @@
+/**
+ * 전체 경로 기반 가지 키를 HTML id로 변환 · 제목이 같은 묶음·문서도 독립 제어
+ */
+export const toNavigationBranchId = (key: string) => {
+    return `fh-branch-${encodeURIComponent(key)}`;
+};

package/src/component/widget/navigation/_function/to-navigation-data/_to-navigation-document.ts

@@ -0,0 +1,14 @@
+import type {DocBranch} from "@/component/widget/navigation/_type/doc-branch";
+import type {NavigationDoc} from "@/component/widget/navigation/_type/navigation-data";
+
+/**
+ * 本문 없는 문서 가지 · 재귀에서도 현재 페이지와 조상 경로만 유지
+ */
+export const toNavigationDocument = (options: {doc: DocBranch; current?: string; ancestors: Set<string>}): NavigationDoc => ({
+    id: options.doc.id,
+    name: options.doc.data.name,
+    label: options.doc.data.label,
+    active: options.doc.id === options.current,
+    current: options.doc.id === options.current || options.ancestors.has(options.doc.id),
+    children: options.doc.children === undefined ? [] : options.doc.children.map((doc) => toNavigationDocument({...options, doc})),
+});

package/src/component/widget/navigation/_function/to-navigation-data/_to-navigation-group.ts

@@ -0,0 +1,14 @@
+import {toNavigationDocument} from "@/component/widget/navigation/_function/to-navigation-data/_to-navigation-document";
+import type {DocGroup} from "@/component/widget/navigation/_type/doc-group";
+import type {NavigationGroup} from "@/component/widget/navigation/_type/navigation-data";
+
+/**
+ * 전체 묶음 경로와 본문 없는 하위 가지 · 현재 문서의 경로만 트리선으로 연결
+ */
+export const toNavigationGroup = (options: {group: DocGroup; current?: string; ancestors: Set<string>; currentGroup?: string[]}): NavigationGroup => ({
+    name: options.group.name,
+    path: options.group.path,
+    current: options.group.path.every((name, index) => name === options.currentGroup?.[index]),
+    docs: options.group.docs.map((doc) => toNavigationDocument({doc, current: options.current, ancestors: options.ancestors})),
+    groups: options.group.groups.map((group) => toNavigationGroup({...options, group})),
+});

package/src/component/widget/navigation/_function/to-navigation-data/to-navigation-data.ts

@@ -0,0 +1,25 @@
+import {toDocGroups} from "@/component/widget/navigation/_function/to-doc-groups/to-doc-groups";
+import {toNavigationGroup} from "@/component/widget/navigation/_function/to-navigation-data/_to-navigation-group";
+import {toTocGroups} from "@/component/widget/navigation/_function/to-toc-groups";
+import type {NavigationData} from "@/component/widget/navigation/_type/navigation-data";
+import type {Doc} from "@/type/doc";
+import type {DocOutline} from "@/type/doc-outline";
+import type {SiteConfig} from "@/type/site-config";
+
+/**
+ * 현재 문서의 이름·계층·목차만 전송 · 다른 문서 본문은 브라우저 탐색 입력에서 제외
+ */
+export const toNavigationData = (options: {site: SiteConfig; docs: Doc[]; current?: string; outline?: DocOutline}): NavigationData => {
+    const currentDoc = options.docs.find((doc) => doc.id === options.current);
+    const ancestors = new Set(currentDoc?.ancestors);
+
+    return {
+        title: options.site.title,
+        groups: toDocGroups({docs: options.docs, navigation: options.site.navigation}).map((group) =>
+            toNavigationGroup({group, current: options.current, ancestors, currentGroup: currentDoc?.data.group}),
+        ),
+        outline: options.outline === undefined ? [] : toTocGroups(options.outline),
+        pageId: options.current === undefined ? "/" : options.current,
+        home: options.current === undefined,
+    };
+};

package/src/component/widget/navigation/_function/to-navigation-json.ts

@@ -0,0 +1,8 @@
+import type {NavigationData} from "@/component/widget/navigation/_type/navigation-data";
+
+/**
+ * 작성한 이름이 script 종료 태그나 JavaScript 줄 구분자로 해석되지 않는 JSON
+ */
+export const toNavigationJson = (data: NavigationData) => {
+    return JSON.stringify(data).replaceAll("<", "\\u003c").replaceAll("\u2028", "\\u2028").replaceAll("\u2029", "\\u2029");
+};

package/src/component/widget/{shell → navigation}/_function/to-toc-groups.ts

@@ -1,7 +1,7 @@
 import {takeWhile} from "es-toolkit/array";
+import type {TocGroup, TocSection} from "@/component/widget/navigation/_type/toc-group";
 import {section_heading_depth} from "@/component/widget/prose/_constant/section";
-import type {DocOutline} from "@/component/widget/shell/_type/doc-outline";
-import type {TocGroup, TocSection} from "@/component/widget/shell/_type/toc-group";
+import type {DocOutline} from "@/type/doc-outline";
 
 /**
  * h2별 h3 수집 · 가름 시작 절에서 목차 묶음 분리

package/src/{type → component/widget/navigation/_type}/doc-group.ts

@@ -1,5 +1,5 @@
+import type {DocBranch} from "@/component/widget/navigation/_type/doc-branch";
 import type {Doc} from "@/type/doc";
-import type {DocBranch} from "@/type/doc-branch";
 
 /**
  * 사이드바의 문서 묶음 · 같은 이름도 전체 경로로 구분

package/src/component/widget/navigation/_type/navigation-data.ts

@@ -0,0 +1,83 @@
+import type {TocGroup} from "@/component/widget/navigation/_type/toc-group";
+
+/**
+ * 브라우저 문서 가지 · 본문·파일 경로를 포함하지 않는 탐색 전용 계약
+ */
+export interface NavigationDoc {
+    /**
+     * 링크의 문서 id
+     */
+    id: string;
+    /**
+     * 표시 이름
+     */
+    name: string;
+    /**
+     * 링크의 보조 설명
+     */
+    label: string;
+    /**
+     * 현재 페이지 한 항목만 강조
+     */
+    active: boolean;
+    /**
+     * 현재 문서와 조상의 트리 경로
+     */
+    current: boolean;
+    /**
+     * 클릭 가능한 하위 문서
+     */
+    children: NavigationDoc[];
+}
+
+/**
+ * 클릭하지 않는 문서 묶음 · 같은 이름은 전체 경로로 구분
+ */
+export interface NavigationGroup {
+    /**
+     * 묶음 이름
+     */
+    name: string;
+    /**
+     * 최상위부터 현재 묶음까지
+     */
+    path: string[];
+    /**
+     * 현재 페이지가 속한 묶음 경로
+     */
+    current: boolean;
+    /**
+     * 현재 단계의 문서
+     */
+    docs: NavigationDoc[];
+    /**
+     * 하위 묶음
+     */
+    groups: NavigationGroup[];
+}
+
+/**
+ * 서버가 계산한 최소 탐색 자료 · 서버 출력과 클라이언트 JSX의 공통 입력
+ */
+export interface NavigationData {
+    /**
+     * 브랜드 이름
+     */
+    title: string;
+    /**
+     * 읽는 순서의 문서 트리
+     */
+    groups: NavigationGroup[];
+    /**
+     * 현재 페이지의 목차
+     */
+    outline: TocGroup[];
+    /**
+     * 목차의 접힘 상태를 구분할 문서 id
+     */
+    pageId: string;
+    /**
+     * README 홈 여부
+     */
+    home: boolean;
+}

package/src/component/widget/navigation/_type/navigation-focus-snapshot.ts

@@ -0,0 +1,21 @@
+/**
+ * Hono가 배치 변경에서 이전 DOM의 자식을 분리하기 전에 기억하는 키보드 위치
+ */
+export interface NavigationFocusSnapshot {
+    /**
+     * 문서 탐색 안에서 새 배치로 옮길 위치인지 구분
+     */
+    navigation: boolean;
+    /**
+     * 메뉴 진입·닫기 버튼에서 데스크톱 브랜드로 돌아갈 위치인지 구분
+     */
+    drawer: boolean;
+    /**
+     * 하위 문서·묶음 접힘 버튼의 안정된 식별자
+     */
+    branch: string | null;
+    /**
+     * 문서 이동 링크의 안정된 식별자
+     */
+    href: string | null;
+}

package/src/component/widget/navigation/_wg-navigation-branch-toggle.css

@@ -0,0 +1,28 @@
+/* 각 가지 항목이 위치 기준 · 텍스트 이동과 독립된 접기 동작 */
+.wg_navigationBranchToggle__root {
+    position: absolute;
+    top: 0;
+    right: 0;
+    width: var(--app-size-tree-toggle);
+    height: calc(var(--app-font-size-dense) * var(--app-line-height-tight) + var(--app-space-tree-row) * 2);
+    padding: 0;
+    border: 0;
+    background: transparent;
+    color: var(--app-color-border-soft);
+    font-family: var(--app-font-mono);
+    font-size: var(--app-font-size-body);
+    line-height: 1;
+    cursor: pointer;
+
+    &:hover {
+        background: var(--app-color-accent-soft);
+        color: var(--app-color-text-strong);
+    }
+
+    &:focus-visible {
+        background: var(--app-color-accent-soft);
+        color: var(--app-color-text-strong);
+        outline: var(--app-outline-focus);
+        outline-offset: calc(0px - var(--app-outline-focus-offset));
+    }
+}

package/src/component/widget/navigation/_wg-navigation-branch-toggle.tsx

@@ -0,0 +1,48 @@
+import clsx from "clsx";
+import {toNavigationBranchId} from "@/component/widget/navigation/_function/to-navigation-branch-id";
+import "./_wg-navigation-branch-toggle.css";
+
+/**
+ * 문서·목차에서 공유하는 가지 조작 · 링크 이동과 분리된 네이티브 버튼
+ */
+export interface WgNavigationBranchToggleProps {
+    /**
+     * 문서 ID·묶음 경로·페이지별 헤딩으로 구분한 상태 키
+     */
+    branchKey: string;
+    /**
+     * 펼치거나 접을 가지의 접근 가능한 이름
+     */
+    label: string;
+    /**
+     * 같은 저장 키의 접힘 상태
+     */
+    collapsed: Record<string, boolean>;
+    /**
+     * 브라우저에서만 제공하는 가지 변경 동작
+     */
+    onToggle?: (key: string) => void;
+}
+
+export const WgNavigationBranchToggle = (props: WgNavigationBranchToggleProps) => {
+    /**
+     * 링크 이동과 별도로 현재 가지 선택 변경
+     */
+    const handleToggleClick = () => props.onToggle?.(props.branchKey);
+
+    return (
+        <button
+            className={clsx("wg_navigationBranchToggle__root")}
+            type="button"
+            aria-label={`${props.collapsed[props.branchKey] === true ? "Expand" : "Collapse"} ${props.label}`}
+            aria-expanded={String(props.collapsed[props.branchKey] !== true)}
+            aria-controls={toNavigationBranchId(props.branchKey)}
+            data-navigation-toggle={props.branchKey}
+            data-navigation-label={props.label}
+            hidden={props.onToggle === undefined}
+            onClick={handleToggleClick}
+        >
+            {props.collapsed[props.branchKey] === true ? "+" : "−"}
+        </button>
+    );
+};