for-humanity 0.4.3 → 0.5.0

package/src/component/widget/{shell/_wg-shell-nav-list.css → navigation/_wg-navigation-nav-list.css}

@@ -1,13 +1,13 @@
 /*
  * 재귀 문서 목록 · 단계별 가지와 조상 경로의 1px 트리
  */
-.wg_shellNavList__root {
+.wg_navigationNavList__root {
     margin: 0 0 0 var(--app-space-tree-inset);
     padding: 0;
     list-style: none;
 }
 
-.wg_shellNavList__branch {
+.wg_navigationNavList__branch {
     /* 하위 묶음도 문서와 같은 첫 줄 기준으로 가지 연결 */
     position: relative;
     display: block;
@@ -28,7 +28,7 @@
     }
 }
 
-.wg_shellNavList__link {
+.wg_navigationNavList__link {
     /* 가로 가지는 링크 첫 줄 기준 · 여러 줄 제목에서도 연결 위치 유지 */
     position: relative;
     display: block;
@@ -68,7 +68,7 @@
     }
 }
 
-.wg_shellNavList__link--active {
+.wg_navigationNavList__link--active {
     color: var(--app-color-link);
     font-weight: var(--app-font-weight-active);
 
@@ -77,13 +77,21 @@
     }
 }
 
-.wg_shellNavList__item {
+.wg_navigationNavList__item {
     /* 하위 목록을 포함해 다음 형제까지 줄기 연결 */
     display: flow-root;
 
     /* 세로 줄기는 각 항목 기준 · 마지막 항목의 첫 줄 가운데에서 종료 */
     position: relative;
 
+    &:has(> .wg_navigationBranchToggle__root) > .wg_navigationNavList__link {
+        padding-inline-end: calc(var(--app-size-tree-toggle) + var(--app-space-inline));
+    }
+
+    &:has(> .wg_navigationBranchToggle__root) > .wg_navigationNavList__branch {
+        padding-inline-end: calc(var(--app-size-tree-toggle) + var(--app-space-inline));
+    }
+
     &::before {
         position: absolute;
         top: 0;
@@ -119,53 +127,53 @@
     }
 
     /* 뒤 항목까지의 세로 경로 · 같은 목록의 형제 안에서만 연결 */
-    &:where(:has(~ .wg_shellNavList__item:hover))::before {
+    &:where(:has(~ .wg_navigationNavList__item:hover))::before {
         border-left-color: var(--app-color-link);
     }
 
-    &:where(:has(~ .wg_shellNavList__item :focus-visible))::before {
+    &:where(:has(~ .wg_navigationNavList__item :focus-visible))::before {
         border-left-color: var(--app-color-link);
     }
 
-    & > .wg_shellNavList__root {
+    & > .wg_navigationNavList__root {
         margin-left: var(--app-space-tree-indent);
     }
 
     /* 하위 문서를 탐색할 때 조상 묶음의 가지도 함께 연결 */
-    &:where(:hover) > .wg_shellNavList__branch::before {
+    &:where(:hover) > .wg_navigationNavList__branch::before {
         border-top-color: var(--app-color-link);
     }
 
-    &:where(:has(:focus-visible)) > .wg_shellNavList__branch::before {
+    &:where(:has(:focus-visible)) > .wg_navigationNavList__branch::before {
         border-top-color: var(--app-color-link);
     }
 
     /* 자식 문서를 탐색할 때 클릭 가능한 부모 문서의 가지도 연결 */
-    &:where(:hover) > .wg_shellNavList__link::before {
+    &:where(:hover) > .wg_navigationNavList__link::before {
         border-top-color: var(--app-color-link);
     }
 
-    &:where(:has(:focus-visible)) > .wg_shellNavList__link::before {
+    &:where(:has(:focus-visible)) > .wg_navigationNavList__link::before {
         border-top-color: var(--app-color-link);
     }
 }
 
-.wg_shellNavList__item--trail {
+.wg_navigationNavList__item--trail {
     &::before {
         border-left-color: var(--app-color-link);
     }
 }
 
-.wg_shellNavList__item--current {
+.wg_navigationNavList__item--current {
     &::after {
         border-left-color: var(--app-color-link);
     }
 
-    & > .wg_shellNavList__branch::before {
+    & > .wg_navigationNavList__branch::before {
         border-top-color: var(--app-color-link);
     }
 
-    & > .wg_shellNavList__link::before {
+    & > .wg_navigationNavList__link::before {
         border-top-color: var(--app-color-link);
     }
 }

package/src/component/widget/navigation/_wg-navigation-nav-list.tsx

@@ -0,0 +1,106 @@
+import clsx from "clsx";
+import {Fragment} from "hono/jsx";
+import {toNavigationBranchId} from "@/component/widget/navigation/_function/to-navigation-branch-id";
+import type {NavigationGroup} from "@/component/widget/navigation/_type/navigation-data";
+import {WgNavigationBranchToggle} from "@/component/widget/navigation/_wg-navigation-branch-toggle";
+import "./_wg-navigation-nav-list.css";
+
+/**
+ * 한 단계의 문서 목록과 하위 묶음 · 재귀에서도 같은 탐색 표현 유지
+ */
+export interface WgNavigationNavListProps {
+    /**
+     * 현재 단계의 문서와 하위 묶음
+     */
+    group: NavigationGroup;
+    /**
+     * 사용자가 접은 가지
+     */
+    collapsed: Record<string, boolean>;
+    /**
+     * 브라우저에서 가지 선택 변경
+     */
+    onToggle?: (key: string) => void;
+    /**
+     * 부모 버튼과 연결할 가지 키 · 루트 묶음·문서 모두 같은 규칙 사용
+     */
+    branchKey: string;
+}
+
+export const WgNavigationNavList = (props: WgNavigationNavListProps) => {
+    const entries = [
+        ...props.group.docs.map((doc) => {
+            const active = doc.active;
+            return {kind: "document" as const, key: `doc:${doc.id}`, doc, active, current: doc.current};
+        }),
+        ...props.group.groups.map((group) => ({
+            kind: "group" as const,
+            key: `group:${JSON.stringify(group.path)}`,
+            group,
+            current: group.current,
+        })),
+    ];
+    const currentIndex = entries.findIndex((entry) => entry.current);
+
+    return (
+        <ul
+            className={clsx("wg_navigationNavList__root")}
+            aria-label={props.group.name}
+            id={toNavigationBranchId(props.branchKey)}
+            hidden={props.collapsed[props.branchKey] === true}
+        >
+            {/**
+             * 현재 경로 앞의 줄기와 도착 가지 · 문서 링크는 원래 파일 URL 사용
+             */}
+            {entries.map((entry, index) => (
+                <li
+                    className={clsx("wg_navigationNavList__item", {
+                        "wg_navigationNavList__item--trail": index < currentIndex,
+                        "wg_navigationNavList__item--current": entry.current,
+                    })}
+                    key={entry.key}
+                >
+                    {/**
+                     * 문서 링크 · 부모도 독립 페이지, 현재 한 문서에만 페이지 상태 부여
+                     */}
+                    {entry.kind === "document" && (
+                        <Fragment>
+                            <a
+                                className={clsx("wg_navigationNavList__link", {"wg_navigationNavList__link--active": entry.active})}
+                                href={`/${entry.doc.id}/`}
+                                title={entry.doc.label}
+                                aria-current={entry.active ? "page" : undefined}
+                            >
+                                {entry.doc.name}
+                            </a>
+                            {/**
+                             * 하위 문서 · 부모 아래에서도 기존 목록의 들여쓰기와 키보드 이동 유지
+                             */}
+                            {entry.doc.children.length > 0 && (
+                                <WgNavigationBranchToggle branchKey={entry.key} label={entry.doc.name} collapsed={props.collapsed} onToggle={props.onToggle} />
+                            )}
+                            {entry.doc.children.length > 0 && (
+                                <WgNavigationNavList
+                                    group={{name: entry.doc.name, path: props.group.path, current: entry.current, docs: entry.doc.children, groups: []}}
+                                    collapsed={props.collapsed}
+                                    onToggle={props.onToggle}
+                                    branchKey={entry.key}
+                                />
+                            )}
+                        </Fragment>
+                    )}
+                    {/**
+                     * 하위 묶음 · 같은 목록을 재귀로 이어 깊이에 따라 들여쓰기
+                     */}
+                    {entry.kind === "group" && (
+                        <Fragment>
+                            <span className={clsx("wg_navigationNavList__branch")}>{entry.group.name}</span>
+                            <WgNavigationBranchToggle branchKey={entry.key} label={entry.group.name} collapsed={props.collapsed} onToggle={props.onToggle} />
+                            <WgNavigationNavList group={entry.group} collapsed={props.collapsed} onToggle={props.onToggle} branchKey={entry.key} />
+                        </Fragment>
+                    )}
+                </li>
+            ))}
+        </ul>
+    );
+};

package/src/component/widget/{shell/_wg-shell-nav.css → navigation/_wg-navigation-nav.css}

@@ -1,21 +1,27 @@
 /*
  * 읽는 순서의 문서 목록 · 작은 회색 묶음과 링크색 문서
  */
-.wg_shellNav__root {
+.wg_navigationNav__root {
     font-size: var(--app-font-size-dense);
     line-height: var(--app-line-height-tight);
 }
 
-.wg_shellNav__docs {
+.wg_navigationNav__docs {
     display: flex;
     flex-direction: column;
     gap: var(--app-space-stack);
 }
 
-.wg_shellNav__group {
+.wg_navigationNav__group {
+    padding-inline-end: calc(var(--app-size-tree-toggle) + var(--app-space-inline));
     margin: 0 0 4px;
     color: var(--app-color-text-muted);
     font-size: var(--app-font-size-group);
     line-height: calc(var(--app-font-size-dense) * var(--app-line-height-tight));
     text-box: trim-start cap alphabetic;
 }
+
+.wg_navigationNav__docGroup {
+    /* 묶음 접기 버튼의 첫 행 기준 */
+    position: relative;
+}

package/src/component/widget/navigation/_wg-navigation-nav.tsx

@@ -0,0 +1,43 @@
+import clsx from "clsx";
+import type {NavigationGroup} from "@/component/widget/navigation/_type/navigation-data";
+import {WgNavigationBranchToggle} from "@/component/widget/navigation/_wg-navigation-branch-toggle";
+import {WgNavigationNavList} from "@/component/widget/navigation/_wg-navigation-nav-list";
+import {copy_nav_aria_label} from "@/constant/copy";
+import "./_wg-navigation-nav.css";
+
+/**
+ * 서버·브라우저가 공유하는 문서 트리
+ */
+export interface WgNavigationNavProps {
+    /**
+     * 본문을 제외한 읽는 순서의 문서 묶음
+     */
+    groups: NavigationGroup[];
+    /**
+     * 사용자가 접은 가지
+     */
+    collapsed: Record<string, boolean>;
+    /**
+     * 브라우저에서 가지 선택 변경 · 서버 출력에서는 생략
+     */
+    onToggle?: (key: string) => void;
+}
+
+export const WgNavigationNav = (props: WgNavigationNavProps) => {
+    return (
+        <nav className={clsx("wg_navigationNav__root")} aria-label={copy_nav_aria_label}>
+            {/**
+             * 문서 이동 · 클릭하지 않는 묶음과 독립 문서
+             */}
+            <div className={clsx("wg_navigationNav__docs")}>
+                {props.groups.map((group) => (
+                    <section className={clsx("wg_navigationNav__docGroup")} key={JSON.stringify(group.path)} aria-label={group.name}>
+                        <div className={clsx("wg_navigationNav__group")}>{group.name}</div>
+                        <WgNavigationBranchToggle branchKey={`group:${JSON.stringify(group.path)}`} label={group.name} collapsed={props.collapsed} onToggle={props.onToggle} />
+                        <WgNavigationNavList group={group} branchKey={`group:${JSON.stringify(group.path)}`} collapsed={props.collapsed} onToggle={props.onToggle} />
+                    </section>
+                ))}
+            </div>
+        </nav>
+    );
+};

package/src/component/widget/navigation/_wg-navigation-scroll.tsx

@@ -0,0 +1,117 @@
+import clsx from "clsx";
+import {type Child, type DOMAttributes, type RefObject, useLayoutEffect, useRef, useState} from "hono/jsx";
+
+/**
+ * 탐색 좌표를 제어하는 부모와 넘침 표시를 소유하는 스크롤 영역의 경계
+ */
+export interface WgNavigationScrollProps {
+    /**
+     * 배치별 좌표 복원과 저장에 필요한 실제 스크롤 요소
+     */
+    portRef: RefObject<HTMLDivElement | null>;
+    /**
+     * 문서 목록과 현재 페이지 목차의 독립된 스크롤 수명
+     */
+    kind: "documents" | "outline";
+    /**
+     * JavaScript가 연결된 뒤에만 손잡이를 넘침 표시로 대체
+     */
+    ready: boolean;
+    /**
+     * 탐색 링크를 포함한 영역 내용
+     */
+    children: Child;
+    /**
+     * 이동 직전 좌표 보존과 모바일 모달 닫기
+     */
+    onClick?: DOMAttributes["onClick"];
+    /**
+     * 실제 스크롤 좌표가 바뀔 때 부모 저장소에 반영
+     */
+    onScroll?: () => void;
+}
+
+export const WgNavigationScroll = (props: WgNavigationScrollProps) => {
+    const [overflow, setOverflow] = useState({above: false, below: false});
+    const frameRef = useRef(0);
+
+    /**
+     * 소수 픽셀 반올림을 제외한 실제 남은 내용만 위·아래 흐림으로 알림
+     */
+    const updateOverflow = () => {
+        frameRef.current = 0;
+        if (props.portRef.current === null) return;
+        const above = props.portRef.current.scrollTop > 1;
+        const below = props.portRef.current.scrollHeight - props.portRef.current.clientHeight - props.portRef.current.scrollTop > 1;
+        setOverflow((state) => (state.above === above && state.below === below ? state : {above, below}));
+    };
+
+    /**
+     * 연속 스크롤과 관찰자 알림은 프레임당 한 번 측정
+     */
+    const scheduleOverflow = () => {
+        if (frameRef.current === 0) frameRef.current = requestAnimationFrame(updateOverflow);
+    };
+
+    /**
+     * 네이티브 좌표는 바로 저장하고 시각적 넘침만 프레임에 맞춰 갱신
+     */
+    const handlePortScroll: DOMAttributes["onScroll"] = (_event) => {
+        props.onScroll?.();
+        scheduleOverflow();
+    };
+
+    /**
+     * 영역과 내용의 크기를 함께 추적 · Hono 최초 mount의 분리된 fragment 측정은 연결 직후 실행
+     */
+    useLayoutEffect(() => {
+        if (!props.ready || props.portRef.current === null) return;
+        const observer = new ResizeObserver(scheduleOverflow);
+        observer.observe(props.portRef.current);
+        if (props.portRef.current.firstElementChild !== null) observer.observe(props.portRef.current.firstElementChild);
+        let active = true;
+        addEventListener("pageshow", scheduleOverflow);
+        if (props.portRef.current.isConnected) {
+            updateOverflow();
+        } else {
+            // Hono는 최초 layout effect를 fragment에서 실행하므로 같은 script의 paint 전 microtask에서 측정한다
+            queueMicrotask(() => {
+                if (active) updateOverflow();
+            });
+        }
+        return () => {
+            active = false;
+            observer.disconnect();
+            removeEventListener("pageshow", scheduleOverflow);
+            cancelAnimationFrame(frameRef.current);
+            frameRef.current = 0;
+        };
+    }, [props.portRef, props.ready]);
+
+    /**
+     * 접힘 선택의 렌더가 바뀐 직후 측정 · 좌표 복원은 부모의 연결 후 처리보다 앞서 저장하지 않음
+     */
+    useLayoutEffect(() => {
+        if (props.ready && props.portRef.current?.isConnected) updateOverflow();
+    }, [props.children, props.ready]);
+
+    return (
+        // biome-ignore lint/a11y/noStaticElementInteractions lint/a11y/useKeyWithClickEvents: 부모의 링크 이벤트 위임이며 자식 a·button의 네이티브 키보드 동작을 그대로 소비한다
+        <div
+            ref={props.ready ? props.portRef : undefined}
+            className={clsx(
+                "wg_navigation__scroll",
+                props.kind === "documents" && "wg_navigation__documents",
+                props.kind === "outline" && "wg_navigation__headings",
+                props.ready && "wg_navigation__scroll--ready",
+                props.ready && overflow.above && "wg_navigation__scroll--above",
+                props.ready && overflow.below && "wg_navigation__scroll--below",
+            )}
+            data-navigation-scroll={props.kind}
+            onClick={props.onClick}
+            onScroll={handlePortScroll}
+        >
+            {props.children}
+        </div>
+    );
+};

package/src/component/widget/{shell/_wg-shell-toc.css → navigation/_wg-navigation-toc.css}

@@ -1,15 +1,12 @@
 /*
- * 문서 탐색 아래 목차 · 회색 제목·묶음과 본문 글색의 이동 대상 구분
+ * 와이드 화면의 오른쪽 목차 · 회색 제목·묶음과 본문 글색의 이동 대상 구분
  */
-.wg_shellToc__root {
-    margin-top: var(--app-space-group);
-    padding-top: var(--app-space-group);
-    border-top: 1px solid var(--app-color-border-soft);
+.wg_navigationToc__root {
     font-size: var(--app-font-size-dense);
     line-height: var(--app-line-height-tight);
 }
 
-.wg_shellToc__label {
+.wg_navigationToc__label {
     margin-bottom: var(--app-space-inline);
     color: var(--app-color-text-muted);
     font-size: var(--app-font-size-label);
@@ -17,20 +14,31 @@
     letter-spacing: var(--app-letter-spacing-label);
 }
 
-.wg_shellToc__group {
-    margin: var(--app-space-stack) 0 4px;
+.wg_navigationToc__group {
+    margin: 0 0 4px;
+    padding-inline-end: calc(var(--app-size-tree-toggle) + var(--app-space-inline));
     color: var(--app-color-text-muted);
     font-size: var(--app-font-size-group);
     line-height: calc(var(--app-font-size-dense) * var(--app-line-height-tight));
 }
 
-.wg_shellToc__list {
+.wg_navigationToc__groupSection {
+    /* 가름 제목과 그 하위 목록을 하나의 접힘 대상으로 연결 */
+    position: relative;
+    display: flow-root;
+}
+
+.wg_navigationToc__groupSection--named {
+    margin-top: var(--app-space-stack);
+}
+
+.wg_navigationToc__list {
     margin: 0 0 0 var(--app-space-tree-inset);
     padding: 0;
     list-style: none;
 }
 
-.wg_shellToc__link {
+.wg_navigationToc__link {
     /* 가로 가지는 링크 첫 줄 기준 · 여러 줄 제목에서도 연결 위치 유지 */
     position: relative;
     display: block;
@@ -71,7 +79,7 @@
     }
 }
 
-.wg_shellToc__link--active {
+.wg_navigationToc__link--active {
     color: var(--app-color-text-strong);
     font-weight: var(--app-font-weight-active);
 
@@ -80,13 +88,17 @@
     }
 }
 
-.wg_shellToc__item {
+.wg_navigationToc__item {
     /* 하위 목록의 margin을 포함해 다음 항목까지 줄기 연결 */
     display: flow-root;
 
     /* 세로 줄기는 항목 전체 기준 · 중간 항목의 소제목 옆에서도 연결 */
     position: relative;
 
+    &:has(> .wg_navigationBranchToggle__root) > .wg_navigationToc__link {
+        padding-inline-end: calc(var(--app-size-tree-toggle) + var(--app-space-inline));
+    }
+
     &::before {
         position: absolute;
         top: 0;
@@ -122,43 +134,48 @@
     }
 
     /* 뒤 항목까지의 세로 경로 · 같은 목록의 형제 안에서만 연결 */
-    &:where(:has(~ .wg_shellToc__item:hover))::before {
+    &:where(:has(~ .wg_navigationToc__item:hover))::before {
         border-left-color: var(--app-color-text-strong);
     }
 
-    &:where(:has(~ .wg_shellToc__item :focus-visible))::before {
+    &:where(:has(~ .wg_navigationToc__item :focus-visible))::before {
         border-left-color: var(--app-color-text-strong);
     }
 
     /* 하위 제목을 탐색할 때 상위 절의 가지도 연결 */
-    &:where(:hover) > .wg_shellToc__link::before {
+    &:where(:hover) > .wg_navigationToc__link::before {
         border-top-color: var(--app-color-text-strong);
     }
 
-    &:where(:has(:focus-visible)) > .wg_shellToc__link::before {
+    &:where(:has(:focus-visible)) > .wg_navigationToc__link::before {
         border-top-color: var(--app-color-text-strong);
     }
 }
 
-.wg_shellToc__item--trail {
+.wg_navigationToc__item--trail {
     &::before {
         border-left-color: var(--app-color-text-strong);
     }
 }
 
-.wg_shellToc__item--current {
+.wg_navigationToc__item--current {
     &::after {
         border-left-color: var(--app-color-text-strong);
     }
+
+    /* 현재 소제목의 상위 절은 글 강조 없이 경로의 가로 가지 연결 */
+    & > .wg_navigationToc__link::before {
+        border-top-color: var(--app-color-text-strong);
+    }
 }
 
-.wg_shellToc__sub {
+.wg_navigationToc__sub {
     margin: var(--app-space-tree-row) 0 4px var(--app-space-tree-indent);
     padding: 0;
     list-style: none;
 }
 
-.wg_shellToc__subItem {
+.wg_navigationToc__subItem {
     /* 하위 줄기는 소제목 항목 기준 · 마지막 소제목 첫 줄에서 종료 */
     position: relative;
 
@@ -197,28 +214,28 @@
     }
 
     /* 뒤 항목까지의 세로 경로 · 같은 목록의 형제 안에서만 연결 */
-    &:where(:has(~ .wg_shellToc__subItem:hover))::before {
+    &:where(:has(~ .wg_navigationToc__subItem:hover))::before {
         border-left-color: var(--app-color-text-strong);
     }
 
-    &:where(:has(~ .wg_shellToc__subItem :focus-visible))::before {
+    &:where(:has(~ .wg_navigationToc__subItem :focus-visible))::before {
         border-left-color: var(--app-color-text-strong);
     }
 }
 
-.wg_shellToc__subItem--trail {
+.wg_navigationToc__subItem--trail {
     &::before {
         border-left-color: var(--app-color-text-strong);
     }
 }
 
-.wg_shellToc__subItem--current {
+.wg_navigationToc__subItem--current {
     &::after {
         border-left-color: var(--app-color-text-strong);
     }
 }
 
-.wg_shellToc__subLink {
+.wg_navigationToc__subLink {
     /* 하위 가지도 링크 첫 줄 기준 · 줄바꿈된 제목 옆으로 선이 늘어나지 않음 */
     position: relative;
     display: block;
@@ -259,7 +276,7 @@
     }
 }
 
-.wg_shellToc__subLink--active {
+.wg_navigationToc__subLink--active {
     color: var(--app-color-text-strong);
     font-weight: var(--app-font-weight-active);