for-humanity 0.4.3 → 0.5.0

package/src/store/navigation/to-navigation-scroll-state.ts

@@ -0,0 +1,42 @@
+import type {NavigationPosition, NavigationScrollState} from "@/store/navigation/navigation-state";
+
+/**
+ * 알 수 없는 저장 형태·음수·무한 좌표 제외 · 초기 HTML과 Zustand에 같은 검증 적용
+ */
+export const toNavigationScrollState = (value: unknown): NavigationScrollState => {
+    /**
+     * 한 배치의 완전한 좌표만 복원 대상으로 수용
+     */
+    const toPosition = (position: unknown): NavigationPosition | undefined => {
+        if (
+            typeof position !== "object" ||
+            position === null ||
+            !("navigation" in position) ||
+            typeof position.navigation !== "string" ||
+            !("pathname" in position) ||
+            typeof position.pathname !== "string" ||
+            !("documents" in position) ||
+            typeof position.documents !== "number" ||
+            !Number.isFinite(position.documents) ||
+            position.documents < 0 ||
+            !("outline" in position) ||
+            typeof position.outline !== "number" ||
+            !Number.isFinite(position.outline) ||
+            position.outline < 0
+        ) {
+            return;
+        }
+        return {navigation: position.navigation, pathname: position.pathname, documents: position.documents, outline: position.outline};
+    };
+
+    if (typeof value !== "object" || value === null || !("positions" in value) || typeof value.positions !== "object" || value.positions === null) {
+        return {positions: {}};
+    }
+
+    const positions = {
+        wide: toPosition("wide" in value.positions ? value.positions.wide : undefined),
+        desktop: toPosition("desktop" in value.positions ? value.positions.desktop : undefined),
+        drawer: toPosition("drawer" in value.positions ? value.positions.drawer : undefined),
+    };
+    return {positions: Object.fromEntries(Object.entries(positions).filter((entry) => entry[1] !== undefined))};
+};

package/src/store/navigation/to-navigation-tree-state.ts

@@ -0,0 +1,19 @@
+import type {NavigationTreeState} from "@/store/navigation/navigation-state";
+
+/**
+ * persist 저장 자료에서 boolean 접힘 선택만 수용
+ */
+export const toNavigationTreeState = (value: unknown): NavigationTreeState => {
+    if (
+        typeof value !== "object" ||
+        value === null ||
+        !("collapsed" in value) ||
+        typeof value.collapsed !== "object" ||
+        value.collapsed === null ||
+        Array.isArray(value.collapsed)
+    ) {
+        return {collapsed: {}};
+    }
+
+    return {collapsed: Object.fromEntries(Object.entries(value.collapsed).filter((entry) => typeof entry[1] === "boolean"))};
+};

package/src/store/navigation/use-navigation-tree-store.ts

@@ -0,0 +1,12 @@
+import {useSyncExternalStore} from "hono/jsx";
+import {tree_server_state} from "@/store/navigation/_constant/tree";
+import type {createNavigationStores} from "@/store/navigation/create-navigation-stores";
+
+/**
+ * Hono 컴포넌트의 persist 구독 · 브라우저 최초 렌더도 저장된 값을 즉시 소비
+ */
+export const useNavigationTreeStore = (tree?: ReturnType<typeof createNavigationStores>["tree"]) => {
+    const subscribe = tree === undefined ? () => () => {} : tree.subscribe;
+    const getSnapshot = tree === undefined ? () => tree_server_state : tree.getState;
+    return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+};

package/src/style/token.css

@@ -1,7 +1,7 @@
 /*
  * 공통 토큰의 단일 출처 · --app-종류-쓰임
  * 사용 기준: templates/document/design.md · 테마 분기는 color-scheme에 한정
- * 폭 기준 1024px·640px · 공유 사이드바와 본문 배치
+ * 폭 기준 1536px·1024px·640px · 양쪽 탐색과 본문 배치
  */
 
 :root {
@@ -102,13 +102,15 @@
     --app-space-gutter: 28px;
     --app-space-column: 32px;
     --app-space-sidebar-gap: 32px;
-    --app-size-sidebar: 200px;
+    --app-size-sidebar: 240px;
     --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;
+    --app-size-navigation-fade: 28px;
+    --app-size-tree-toggle: 24px;
 
     /* 화면 위쪽 제목 여백 · hash 도착점과 목차 읽는 선의 공통 기준 */
     --app-space-anchor: 80px;

package/src/type/doc-content.ts

@@ -1,4 +1,4 @@
-import type {DocOutline} from "@/component/widget/shell/_type/doc-outline";
+import type {DocOutline} from "@/type/doc-outline";
 
 /**
  * README 홈과 일반 문서가 공유하는 렌더링 결과

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

@@ -1,6 +1,6 @@
-import type {DocSection} from "@/component/widget/prose/_type/doc-section";
 import type {DocData} from "@/type/doc-data";
 import type {DocHeading} from "@/type/doc-heading";
+import type {DocSection} from "@/type/doc-section";
 
 /**
  * 문서 처리 중간 계약 · read-docs의 머리말과 rehype의 제목·절 정보

package/src/{component/widget/shell/_type → type}/doc-outline.ts

@@ -1,5 +1,5 @@
-import type {DocSection} from "@/component/widget/prose/_type/doc-section";
 import type {DocHeading} from "@/type/doc-heading";
+import type {DocSection} from "@/type/doc-section";
 
 /**
  * 문서 렌더링 결과의 목차 입력

package/src/type/site-assets.ts

@@ -7,9 +7,9 @@ export interface SiteAssets {
      */
     stylePath: string;
     /**
-     * 내용 지문으로 구분한 브라우저 스크립트 URL
+     * 셸 DOM 뒤에서 동기 실행할 단일 Hono JSX 브라우저 번들
      */
-    clientPath: string;
+    browserScript: string;
     /**
      * 내장 @font-face · head의 style 내용
      */

package/dist/client.js

@@ -1,6 +0,0 @@
-var T="fh-cursor-face";var w="(width < 1024px)",x="for-humanity:navigation-scroll";var b=e=>{if(!e)return null;try{return document.getElementById(decodeURIComponent(e.slice(1)))}catch(t){if(t instanceof URIError)return null;throw t}};var y=e=>{let t=b(e);for(let n=t?.closest("details");n;n=n.parentElement?.closest("details"))n.open=!0;return t};var I=()=>{let e=document.querySelector("[data-navigation]"),t=document.querySelector("[data-navigation-drawer]"),n=document.querySelector("[data-navigation-content]"),a=document.querySelector("[data-navigation-open]"),s=document.querySelector("[data-navigation-close]"),u=e?.parentElement;if(!e||!t||!n||!a||!s||!u)return;let d=matchMedia(w),l=()=>{t.open||(document.body.classList.remove("wg_shell__root--drawerOpen"),a.setAttribute("aria-expanded","false"))},m=()=>{t.close(),l()},g=()=>{!d.matches||t.open||(t.showModal(),document.body.classList.add("wg_shell__root--drawerOpen"),a.setAttribute("aria-expanded","true"))},i=r=>{let o=t.getBoundingClientRect();r.target===t&&(r.clientX<o.left||r.clientX>o.right||r.clientY<o.top||r.clientY>o.bottom)&&m()},L=r=>{if(!t.open||r.defaultPrevented||r.button!==0||r.metaKey||r.ctrlKey||r.shiftKey||r.altKey||!(r.target instanceof Element))return;let o=r.target.closest("a[href]");if(!(!(o instanceof HTMLAnchorElement)||o.target!==""&&o.target!=="_self"||o.hasAttribute("download"))&&(m(),o.origin===location.origin&&o.pathname===location.pathname&&o.search===location.search&&o.hash)){let c=y(o.hash);c&&(c.tabIndex=-1,c.focus({preventScroll:!0}))}},p=()=>{let r=document.activeElement;if(d.matches){a.classList.add("wg_shell__menuToggle--visible"),n.append(e),r instanceof HTMLElement&&e.contains(r)&&a.focus({preventScroll:!0});return}m(),u.append(e),r instanceof HTMLElement&&e.contains(r)?r.focus({preventScroll:!0}):(r===a||r instanceof HTMLElement&&t.contains(r))&&u.querySelector(".wg_shell__brand")?.focus({preventScroll:!0}),a.classList.remove("wg_shell__menuToggle--visible")};a.addEventListener("click",g),s.addEventListener("click",m),t.addEventListener("close",l),t.addEventListener("click",i),e.addEventListener("click",L),d.addEventListener("change",p),p(),u.classList.add("wg_shell__sidebar--navigationReady")};var N=()=>{let e=document.querySelector("[data-navigation]"),t=document.querySelector(".wg_shell__sidebar"),n=document.querySelector("[data-navigation-drawer]"),a=document.querySelector("[data-navigation-open]");if(!e||!t||!n||!a)return;let s=matchMedia(w),u={mobile:s.matches},d=[...e.querySelectorAll(".wg_shellNav__root a[href]")].map(o=>`${o.pathname}:${o.textContent}`).join(`
-`),l=new Map,m=new Map([[t,`${x}:desktop`],[n,`${x}:drawer`]]),g=new AbortController;for(let[o,c]of m){try{let _=sessionStorage.getItem(c);if(_!==null){let h=JSON.parse(_);typeof h=="object"&&h!==null&&"navigation"in h&&h.navigation===d&&"top"in h&&typeof h.top=="number"&&Number.isFinite(h.top)&&h.top>=0&&l.set(o,h.top)}}catch{}for(let _ of["wheel","touchstart","pointerdown","keydown"])o.addEventListener(_,()=>g.abort(),{once:!0,passive:!0})}let i=new Map(l),L=()=>{u.mobile=s.matches;let o=s.matches?n:t,c=l.get(o);c===void 0||s.matches&&!n.open||(o.scrollTop=c)},p=o=>{let c=s.matches?n:t,_=m.get(c);if(!(u.mobile!==s.matches||o.type==="scroll"&&o.currentTarget!==c||_===void 0||s.matches&&!n.open)){l.set(c,c.scrollTop);try{sessionStorage.setItem(_,JSON.stringify({navigation:d,top:c.scrollTop}))}catch{}}},r=async()=>{if(await document.fonts.ready,!g.signal.aborted){let o=s.matches?n:t,c=i.get(o);c!==void 0&&(!s.matches||n.open)&&(o.scrollTop=c)}};t.addEventListener("scroll",p,{passive:!0}),n.addEventListener("scroll",p,{passive:!0}),e.addEventListener("click",p,{capture:!0}),a.addEventListener("click",L),s.addEventListener("change",L),addEventListener("pagehide",p),L(),document.readyState==="complete"?r():addEventListener("load",r,{once:!0})};I();N();var f=document.querySelector("[data-cursor-face]");if(f){let e=matchMedia("(hover: hover) and (pointer: fine) and (prefers-reduced-motion: no-preference)"),t={x:0,y:0,frame:0},n=()=>{cancelAnimationFrame(t.frame),t.frame=0,f.classList.remove("wg_shell__cursorFace--visible")},a=()=>{e.matches||n()},s=()=>{t.frame===0&&(t.frame=requestAnimationFrame(()=>{t.frame=0,f.style.transform=`translate3d(
-                ${Math.max(0,Math.min(t.x+16,document.documentElement.clientWidth-f.width-16))}px,
-                ${Math.max(0,Math.min(t.y+16,document.documentElement.clientHeight-f.height-16))}px,
-                0
-            )`,f.classList.add("wg_shell__cursorFace--visible")}))},u=g=>{if(!(e.matches&&g.pointerType==="mouse")){n();return}t.x=g.clientX,t.y=g.clientY,s()},d=()=>{f.classList.contains("wg_shell__cursorFace--visible")&&s()},l=()=>{if(f.classList.contains("wg_shell__cursorFace--visible"))try{sessionStorage.setItem(T,JSON.stringify({x:t.x,y:t.y}))}catch{}},m=()=>{try{let g=sessionStorage.getItem(T);if(sessionStorage.removeItem(T),g!==null&&e.matches){let i=JSON.parse(g);typeof i=="object"&&i!==null&&"x"in i&&"y"in i&&typeof i.x=="number"&&typeof i.y=="number"&&Number.isFinite(i.x)&&Number.isFinite(i.y)&&(t.x=i.x,t.y=i.y,s())}}catch{}};m(),document.addEventListener("pointermove",u,{passive:!0}),document.addEventListener("pointerdown",u,{passive:!0}),document.documentElement.addEventListener("pointerleave",n),addEventListener("blur",n),addEventListener("resize",d),addEventListener("pagehide",l),addEventListener("pageshow",m),e.addEventListener("change",a)}var k=y(location.hash),E=null,S=0,v=null,C=()=>{clearTimeout(S),v?.abort(),v=null,E?.classList.remove("wg_prose__headingText--highlighted"),E=null},q=e=>{C(),E=e===null?null:e.querySelector(".wg_prose__headingText"),E!==null&&(E.classList.add("wg_prose__headingText--highlighted"),S=window.setTimeout(C,3e3),v=new AbortController,document.addEventListener("scrollend",P,{signal:v.signal}))},P=e=>{e.target===document&&(clearTimeout(S),v?.abort(),v=null,S=window.setTimeout(C,3e3))},R=e=>{if(!(e.defaultPrevented||e.button!==0||e.metaKey||e.ctrlKey||e.shiftKey||e.altKey)&&e.currentTarget instanceof HTMLAnchorElement&&(e.currentTarget.target===""||e.currentTarget.target==="_self")&&!e.currentTarget.hasAttribute("download")&&e.currentTarget.origin===location.origin&&e.currentTarget.pathname===location.pathname&&e.currentTarget.search===location.search&&e.currentTarget.hash){let t=y(e.currentTarget.hash);e.currentTarget.hash===location.hash&&q(t)}},$=()=>{let e=y(location.hash);e?.scrollIntoView(),q(e)};for(let e of document.querySelectorAll("a[href]"))e.addEventListener("click",R);addEventListener("hashchange",$);var H=[...document.querySelectorAll("[data-toc-link]")].flatMap(e=>{let t=b(e.hash),n=e.parentElement;return!t||!n?[]:[{heading:t,link:e,item:n,list:n.parentElement,subs:[...n.querySelectorAll("[data-toc-sub-link]")].flatMap(a=>{let s=b(a.hash),u=a.parentElement;return s&&u?[{heading:s,link:a,item:u}]:[]})}]}),A=H.at(0);if(A){let e=()=>{let t=Number.parseFloat(getComputedStyle(A.heading).scrollMarginTop)+1,n=H.findLast(d=>d.heading.checkVisibility()&&d.heading.getBoundingClientRect().top<=t)??A,a=n.subs.findLast(d=>d.heading.checkVisibility()&&d.heading.getBoundingClientRect().top<=t),s=H.indexOf(n),u=a===void 0?-1:n.subs.indexOf(a);for(let[d,l]of H.entries()){let m=l===n&&a===void 0;l.link.classList.toggle("wg_shellToc__link--active",m),m?l.link.setAttribute("aria-current","location"):l.link.removeAttribute("aria-current"),l.item.classList.toggle("wg_shellToc__item--trail",l.list===n.list&&d<s),l.item.classList.toggle("wg_shellToc__item--current",l===n);for(let[g,i]of l.subs.entries())i.link.classList.toggle("wg_shellToc__subLink--active",i===a),i===a?i.link.setAttribute("aria-current","location"):i.link.removeAttribute("aria-current"),i.item.classList.toggle("wg_shellToc__subItem--trail",l===n&&g<u),i.item.classList.toggle("wg_shellToc__subItem--current",i===a)}};addEventListener("scroll",e,{passive:!0}),addEventListener("resize",e),addEventListener("toggle",e,!0),e()}var K=new AbortController;for(let e of["wheel","touchmove","keydown","mousedown"])addEventListener(e,()=>K.abort(),{once:!0,passive:!0});var F=async()=>{await document.fonts.ready,k&&!K.signal.aborted&&(k.scrollIntoView({behavior:"instant"}),q(k)),document.documentElement.style.removeProperty("scroll-behavior")};document.readyState==="complete"?F():addEventListener("load",F,{once:!0});

package/src/client.ts

@@ -1,335 +0,0 @@
-/*
- * 브라우저 동작 · 모바일 탐색, 커서 장식, 읽는 절, 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 {bindNavigationScroll} from "@/component/widget/shell/_function/bind-navigation-scroll";
-import {findHashTarget} from "@/util/dom/find-hash-target";
-import {revealHashTarget} from "@/util/dom/reveal-hash-target";
-
-bindMobileNavigation();
-bindNavigationScroll();
-
-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()) {
-            const active = section === current && sub === undefined;
-            section.link.classList.toggle("wg_shellToc__link--active", active);
-            if (active) {
-                section.link.setAttribute("aria-current", "location");
-            } else {
-                section.link.removeAttribute("aria-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);
-                if (item === sub) {
-                    item.link.setAttribute("aria-current", "location");
-                } else {
-                    item.link.removeAttribute("aria-current");
-                }
-                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/shell/_constant/navigation.ts

@@ -1,9 +0,0 @@
-/**
- * 모바일 탐색 전환 · wg-shell.css의 폭 조건과 일치
- */
-export const navigation_mobile_query = "(width < 1024px)";
-
-/**
- * 같은 탭에서 문서 이동 후 탐색 위치 복원 · 데스크톱과 드로어는 별도 저장
- */
-export const navigation_scroll_storage_key = "for-humanity:navigation-scroll";

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

@@ -1,140 +0,0 @@
-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");
-};