for-humanity 0.4.4 → 0.5.0

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

@@ -0,0 +1,155 @@
+import clsx from "clsx";
+import {useLayoutEffect, useState} from "hono/jsx";
+import {reading_line_slack_px} from "@/component/widget/navigation/_constant/reading-line";
+import {toNavigationBranchId} from "@/component/widget/navigation/_function/to-navigation-branch-id";
+import type {TocGroup} from "@/component/widget/navigation/_type/toc-group";
+import {WgNavigationBranchToggle} from "@/component/widget/navigation/_wg-navigation-branch-toggle";
+import {copy_nav_toc_label} from "@/constant/copy";
+import {findHashTarget} from "@/util/dom/find-hash-target";
+import "./_wg-navigation-toc.css";
+
+/**
+ * 현재 문서의 목차 · 읽는 제목 한 항목과 조상 트리선 구분
+ */
+export interface WgNavigationTocProps {
+    /**
+     * 본문 순서의 가름·절·소제목
+     */
+    groups: TocGroup[];
+    /**
+     * 문서별 접힘 상태의 키
+     */
+    pageId: string;
+    /**
+     * 사용자가 접은 가지
+     */
+    collapsed: Record<string, boolean>;
+    /**
+     * 브라우저에서만 제공하는 가지 변경 동작
+     */
+    onToggle?: (key: string) => void;
+}
+
+export const WgNavigationToc = (props: WgNavigationTocProps) => {
+    const [currentSlug, setCurrentSlug] = useState<string>();
+
+    /**
+     * 구독은 연결마다 한 번 설치 · 초기 갱신은 본문 파싱 이후로 미룸
+     */
+    useLayoutEffect(() => {
+        const sections = props.groups.flatMap((group) => group.sections);
+        const headings = sections.flatMap((section) => [section.heading, ...section.subs.map((sub) => sub.heading)]);
+        const frame = {id: 0};
+
+        /**
+         * 접힌 본문 제목은 제외하고 읽는 선을 통과한 마지막 제목 선택
+         */
+        const updateCurrentHeading = () => {
+            frame.id = 0;
+            const visible = headings.flatMap((heading) => {
+                const target = findHashTarget(`#${heading.slug}`);
+                return target?.checkVisibility()
+                    ? [{slug: heading.slug, top: target.getBoundingClientRect().top - Number.parseFloat(getComputedStyle(target).scrollMarginTop)}]
+                    : [];
+            });
+            setCurrentSlug(visible.findLast((heading) => heading.top <= reading_line_slack_px)?.slug ?? visible[0]?.slug);
+        };
+
+        /**
+         * 연속 스크롤은 프레임당 한 번만 읽음
+         */
+        const handleReadingPositionChange = () => {
+            if (frame.id === 0) frame.id = requestAnimationFrame(updateCurrentHeading);
+        };
+
+        addEventListener("scroll", handleReadingPositionChange, {passive: true});
+        addEventListener("resize", handleReadingPositionChange);
+        addEventListener("toggle", handleReadingPositionChange, true);
+        addEventListener("pageshow", handleReadingPositionChange);
+        document.addEventListener("DOMContentLoaded", handleReadingPositionChange);
+        if (document.readyState !== "loading") updateCurrentHeading();
+
+        return () => {
+            cancelAnimationFrame(frame.id);
+            removeEventListener("scroll", handleReadingPositionChange);
+            removeEventListener("resize", handleReadingPositionChange);
+            removeEventListener("toggle", handleReadingPositionChange, true);
+            removeEventListener("pageshow", handleReadingPositionChange);
+            document.removeEventListener("DOMContentLoaded", handleReadingPositionChange);
+        };
+    }, [props.groups]);
+
+    return (
+        <nav className={clsx("wg_navigationToc__root")} aria-label={copy_nav_toc_label}>
+            <div className={clsx("wg_navigationToc__label")}>{copy_nav_toc_label}</div>
+            {/**
+             * 가름별 제목 이동 · 하위 제목이 현재 위치여도 부모 글씨는 강조하지 않음
+             */}
+            {props.groups.map((group) => {
+                const currentIndex = group.sections.findIndex((section) => section.heading.slug === currentSlug || section.subs.some((sub) => sub.heading.slug === currentSlug));
+                const partKey = `outline:${props.pageId}:part:${group.sections[0].heading.slug}`;
+                return (
+                    <div
+                        className={clsx("wg_navigationToc__groupSection", {"wg_navigationToc__groupSection--named": group.part !== undefined})}
+                        key={group.sections[0].heading.slug}
+                    >
+                        {group.part !== undefined && <div className={clsx("wg_navigationToc__group")}>{group.part}</div>}
+                        {group.part !== undefined && <WgNavigationBranchToggle branchKey={partKey} label={group.part} collapsed={props.collapsed} onToggle={props.onToggle} />}
+                        <ul className={clsx("wg_navigationToc__list")} id={toNavigationBranchId(partKey)} hidden={props.collapsed[partKey] === true}>
+                            {group.sections.map((section, index) => {
+                                const currentSubIndex = section.subs.findIndex((sub) => sub.heading.slug === currentSlug);
+                                const sectionKey = `outline:${props.pageId}:heading:${section.heading.slug}`;
+                                return (
+                                    <li
+                                        className={clsx("wg_navigationToc__item", {
+                                            "wg_navigationToc__item--trail": index < currentIndex,
+                                            "wg_navigationToc__item--current": index === currentIndex,
+                                        })}
+                                        key={section.heading.slug}
+                                    >
+                                        <a
+                                            className={clsx("wg_navigationToc__link", {"wg_navigationToc__link--active": section.heading.slug === currentSlug})}
+                                            href={`#${section.heading.slug}`}
+                                            data-toc-link=""
+                                            aria-current={section.heading.slug === currentSlug ? "location" : undefined}
+                                        >
+                                            {section.heading.text}
+                                        </a>
+                                        {section.subs.length > 0 && (
+                                            <WgNavigationBranchToggle branchKey={sectionKey} label={section.heading.text} collapsed={props.collapsed} onToggle={props.onToggle} />
+                                        )}
+                                        {/**
+                                         * 조상과 이전 형제의 트리선은 연결 · 활성 링크는 한 제목만
+                                         */}
+                                        {section.subs.length > 0 && (
+                                            <ul className={clsx("wg_navigationToc__sub")} id={toNavigationBranchId(sectionKey)} hidden={props.collapsed[sectionKey] === true}>
+                                                {section.subs.map((sub, subIndex) => (
+                                                    <li
+                                                        className={clsx("wg_navigationToc__subItem", {
+                                                            "wg_navigationToc__subItem--trail": subIndex < currentSubIndex,
+                                                            "wg_navigationToc__subItem--current": subIndex === currentSubIndex,
+                                                        })}
+                                                        key={sub.heading.slug}
+                                                    >
+                                                        <a
+                                                            className={clsx("wg_navigationToc__subLink", {"wg_navigationToc__subLink--active": sub.heading.slug === currentSlug})}
+                                                            href={`#${sub.heading.slug}`}
+                                                            data-toc-sub-link=""
+                                                            aria-current={sub.heading.slug === currentSlug ? "location" : undefined}
+                                                        >
+                                                            {sub.heading.text}
+                                                        </a>
+                                                    </li>
+                                                ))}
+                                            </ul>
+                                        )}
+                                    </li>
+                                );
+                            })}
+                        </ul>
+                    </div>
+                );
+            })}
+        </nav>
+    );
+};

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

@@ -0,0 +1,282 @@
+.wg_navigation__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_navigation__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_navigation__menuIcon {
+    width: 20px;
+    height: 20px;
+    fill: none;
+    stroke: currentcolor;
+    stroke-linecap: round;
+    stroke-width: 1.5;
+}
+
+.wg_navigation__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_navigation__menuToggle--visible {
+    display: flex;
+}
+
+/* sticky 틀 안에서 문서 목록과 목차의 스크롤 높이를 독립 유지 */
+.wg_navigation__sidebar {
+    grid-area: nav;
+    position: sticky;
+    top: 0;
+    align-self: start;
+    min-width: 0;
+    height: 100dvh;
+    margin-inline-end: var(--app-space-sidebar-gap);
+}
+
+.wg_navigation__documents {
+    /* 모든 배치에서 남은 탐색 높이를 문서 목록 전체에 사용 */
+    flex: 1;
+    min-height: 0;
+}
+
+.wg_navigation__outline {
+    display: flex;
+    flex-direction: column;
+    flex: 1;
+    min-height: 0;
+
+    &:where(:has(.wg_navigation__headings:empty)) {
+        display: none;
+    }
+}
+
+.wg_navigation__headings {
+    flex: 1;
+    min-height: 0;
+}
+
+.wg_navigation__navigation {
+    display: flex;
+    flex-direction: column;
+    height: calc(100dvh - var(--app-size-brand));
+    min-width: 0;
+    min-height: 0;
+}
+
+.wg_navigation__tocRail {
+    /* body의 오른쪽 grid 열 · 문서 스크롤과 독립된 뷰포트 기준 sticky */
+    grid-area: outline;
+    position: sticky;
+    top: 0;
+    align-self: start;
+    min-width: 0;
+    height: 100dvh;
+    margin-inline-start: var(--app-space-sidebar-gap);
+    padding-top: var(--app-size-brand);
+
+    & > .wg_navigation__outline {
+        height: 100%;
+    }
+
+    &:where(:has(.wg_navigation__headings:empty)) {
+        display: none;
+    }
+}
+
+.wg_navigation__scroll {
+    overflow-y: auto;
+    overscroll-behavior-y: contain;
+    scroll-padding-block: var(--app-size-navigation-fade);
+}
+
+.wg_navigation__scroll--ready {
+    /* 흐림으로 넘침을 알릴 때만 손잡이 숨김 · JS 없으면 네이티브 손잡이 유지 */
+    scrollbar-width: none;
+}
+
+.wg_navigation__scroll--above {
+    mask-image: linear-gradient(to bottom, transparent, #000 var(--app-size-navigation-fade));
+}
+
+.wg_navigation__scroll--below {
+    mask-image: linear-gradient(to bottom, #000 calc(100% - var(--app-size-navigation-fade)), transparent);
+}
+
+.wg_navigation__scroll--above.wg_navigation__scroll--below {
+    mask-image: linear-gradient(to bottom, transparent, #000 var(--app-size-navigation-fade), #000 calc(100% - var(--app-size-navigation-fade)), transparent);
+}
+
+.wg_navigation__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);
+    overflow: hidden;
+
+    &::backdrop {
+        background: var(--app-color-backdrop);
+    }
+}
+
+.wg_navigation__drawerHeader {
+    /* 두 스크롤 영역 바깥에서 닫기 버튼 유지 */
+    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_navigation__drawerTitle {
+    margin: 0;
+    font-size: var(--app-font-size-part);
+    font-weight: var(--app-font-weight-strong);
+}
+
+.wg_navigation__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_navigation__drawerContent {
+    min-width: 0;
+    height: calc(100% - var(--app-size-mobile-header) - var(--app-space-block));
+
+    & > .wg_navigation__navigation {
+        height: 100%;
+    }
+}
+
+/* 강제 색상 환경은 흐림 대신 시스템 손잡이로 넘침 표시 */
+@media (forced-colors: active) {
+    .wg_navigation__scroll {
+        mask-image: none;
+        scrollbar-width: thin;
+        scrollbar-color: auto;
+    }
+}
+
+/* 와이드 화면에서만 현재 문서 목차 표시 */
+@media (width < 1536px) {
+    .wg_navigation__tocRail {
+        display: none;
+    }
+}
+
+@media (width < 1024px) {
+    .wg_navigation__sidebar {
+        position: static;
+        height: auto;
+        margin-block-end: var(--app-space-block);
+        margin-inline-end: 0;
+        border-bottom: 1px solid var(--app-color-border-layout);
+    }
+
+    .wg_navigation__sidebar > .wg_navigation__navigation {
+        height: auto;
+    }
+
+    .wg_navigation__sidebar > .wg_navigation__navigation > .wg_navigation__documents {
+        max-height: none;
+    }
+
+    .wg_navigation__sidebar--navigationReady {
+        /* 본문을 스크롤해도 메뉴 진입 유지 · 스크립트 없는 긴 목록에는 적용하지 않음 */
+        position: sticky;
+        top: 0;
+        z-index: var(--app-z-index-sticky);
+        background: var(--app-color-ground);
+    }
+
+    .wg_navigation__brandRow {
+        position: static;
+        height: var(--app-size-mobile-header);
+        padding-block: 0;
+        align-items: center;
+    }
+}