for-humanity 0.12.0 → 0.13.1

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

@@ -1,48 +0,0 @@
-/*
- * 재귀 문서 목록 · 단계별 들여쓰기
- */
-.wg_navigationNavList__root {
-    margin: 0;
-    padding: 0;
-    list-style: none;
-}
-
-.wg_navigationNavList__branch {
-    display: block;
-    padding: var(--app-space-tree-row) 0;
-    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));
-    overflow-wrap: anywhere;
-}
-
-.wg_navigationNavList__link {
-    display: block;
-    padding: var(--app-space-tree-row) 0;
-    color: var(--app-color-link);
-    font-size: var(--app-font-size-dense);
-    line-height: var(--app-line-height-tight);
-    text-decoration: none;
-    overflow-wrap: anywhere;
-
-    &:where(:hover) {
-        text-decoration: underline;
-    }
-
-    /* hover와 같은 밑줄로 키보드 위치 표시 */
-    &:where(:focus-visible) {
-        outline: none;
-        text-decoration: underline;
-    }
-}
-
-.wg_navigationNavList__link--active {
-    color: var(--app-color-link);
-    font-weight: var(--app-font-weight-active);
-}
-
-.wg_navigationNavList__item {
-    & > .wg_navigationNavList__root {
-        margin-left: var(--app-space-tree-indent);
-    }
-}

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

@@ -1,61 +0,0 @@
-import clsx from "clsx";
-import {Fragment} from "hono/jsx";
-import type {NavigationGroup} from "@/component/widget/navigation/_type/navigation-data";
-import "./_wg-navigation-nav-list.css";
-
-/**
- * 한 단계의 문서 목록과 하위 묶음 · 재귀에서도 같은 탐색 표현 유지
- */
-export interface WgNavigationNavListProps {
-    /**
-     * 현재 단계의 문서와 하위 묶음
-     */
-    group: NavigationGroup;
-}
-
-export const WgNavigationNavList = (props: WgNavigationNavListProps) => {
-    const entries = [
-        ...props.group.docs.map((doc) => ({kind: "document" as const, key: `doc:${doc.id}`, doc})),
-        ...props.group.groups.map((group) => ({kind: "group" as const, key: `group:${JSON.stringify(group.path)}`, group})),
-    ];
-
-    return (
-        <ul className={clsx("wg_navigationNavList__root")} aria-label={props.group.name}>
-            {/**
-             * 문서 링크는 원래 파일 URL 사용
-             */}
-            {entries.map((entry) => (
-                <li className={clsx("wg_navigationNavList__item")} key={entry.key}>
-                    {/**
-                     * 문서 링크 · 부모도 독립 페이지, 현재 한 문서에만 페이지 상태 부여
-                     */}
-                    {entry.kind === "document" && (
-                        <Fragment>
-                            <a
-                                className={clsx("wg_navigationNavList__link", {"wg_navigationNavList__link--active": entry.doc.active})}
-                                href={`/${entry.doc.id}/`}
-                                title={entry.doc.label}
-                                aria-current={entry.doc.active ? "page" : undefined}
-                            >
-                                {entry.doc.name}
-                            </a>
-                            {/**
-                             * 하위 문서 · 부모 아래에서도 기존 목록의 들여쓰기와 키보드 이동 유지
-                             */}
-                            {entry.doc.children.length > 0 && <WgNavigationNavList group={{name: entry.doc.name, path: props.group.path, docs: entry.doc.children, groups: []}} />}
-                        </Fragment>
-                    )}
-                    {/**
-                     * 하위 묶음 · 같은 목록을 재귀로 이어 깊이에 따라 들여쓰기
-                     */}
-                    {entry.kind === "group" && (
-                        <Fragment>
-                            <span className={clsx("wg_navigationNavList__branch")}>{entry.group.name}</span>
-                            <WgNavigationNavList group={entry.group} />
-                        </Fragment>
-                    )}
-                </li>
-            ))}
-        </ul>
-    );
-};

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

@@ -1,21 +0,0 @@
-/*
- * 읽는 순서의 문서 목록 · 작은 회색 묶음과 링크색 문서
- */
-.wg_navigationNav__root {
-    font-size: var(--app-font-size-dense);
-    line-height: var(--app-line-height-tight);
-}
-
-.wg_navigationNav__docs {
-    display: flex;
-    flex-direction: column;
-    gap: var(--app-space-tree-group);
-}
-
-.wg_navigationNav__group {
-    margin: 0 0 var(--app-space-tree-label);
-    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;
-}

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

@@ -1,33 +0,0 @@
-import clsx from "clsx";
-import type {NavigationGroup} from "@/component/widget/navigation/_type/navigation-data";
-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[];
-}
-
-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>
-                        <WgNavigationNavList group={group} />
-                    </section>
-                ))}
-            </div>
-        </nav>
-    );
-};

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

@@ -1,117 +0,0 @@
-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/navigation/_wg-navigation-toc.css

@@ -1,91 +0,0 @@
-/*
- * 와이드 화면의 오른쪽 목차 · 라벨·묶음은 문서 탐색의 묶음과 같은 표현
- */
-.wg_navigationToc__root {
-    font-size: var(--app-font-size-dense);
-    line-height: var(--app-line-height-tight);
-}
-
-.wg_navigationToc__label {
-    margin: 0 0 var(--app-space-tree-label);
-    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_navigationToc__group {
-    margin: 0 0 var(--app-space-tree-label);
-    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_navigationToc__groupSection--named {
-    margin-top: var(--app-space-tree-group);
-}
-
-.wg_navigationToc__list {
-    margin: 0;
-    padding: 0;
-    list-style: none;
-}
-
-.wg_navigationToc__link {
-    display: block;
-    padding: var(--app-space-tree-row) 0;
-    color: var(--app-color-text);
-    font-size: var(--app-font-size-dense);
-    line-height: var(--app-line-height-tight);
-    text-decoration: none;
-
-    &:where(:hover) {
-        color: var(--app-color-text-strong);
-        text-decoration: underline;
-    }
-
-    /* 박스 대신 hover와 같은 진한 글·밑줄로 키보드 위치 표시 */
-    &:where(:focus-visible) {
-        outline: none;
-        color: var(--app-color-text-strong);
-        text-decoration: underline;
-    }
-}
-
-.wg_navigationToc__link--active {
-    color: var(--app-color-text-strong);
-    font-weight: var(--app-font-weight-active);
-}
-
-.wg_navigationToc__sub {
-    margin: var(--app-space-tree-row) 0 4px var(--app-space-tree-indent);
-    padding: 0;
-    list-style: none;
-}
-
-.wg_navigationToc__subLink {
-    display: block;
-    padding: var(--app-space-tree-row) 0;
-    color: var(--app-color-text);
-    font-size: var(--app-font-size-detail);
-    line-height: var(--app-line-height-tight);
-    text-decoration: none;
-
-    &:where(:hover) {
-        color: var(--app-color-text-strong);
-        text-decoration: underline;
-    }
-
-    /* 상위 목차와 같은 키보드 표현 */
-    &:where(:focus-visible) {
-        outline: none;
-        color: var(--app-color-text-strong);
-        text-decoration: underline;
-    }
-}
-
-.wg_navigationToc__subLink--active {
-    color: var(--app-color-text-strong);
-    font-weight: var(--app-font-weight-active);
-}

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

@@ -1,114 +0,0 @@
-import clsx from "clsx";
-import {useLayoutEffect, useState} from "hono/jsx";
-import {reading_line_slack_px} from "@/component/widget/navigation/_constant/reading-line";
-import type {TocGroup} from "@/component/widget/navigation/_type/toc-group";
-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[];
-}
-
-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) => (
-                <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>}
-                    <ul className={clsx("wg_navigationToc__list")}>
-                        {group.sections.map((section) => (
-                            <li className={clsx("wg_navigationToc__item")} 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 && (
-                                    <ul className={clsx("wg_navigationToc__sub")}>
-                                        {section.subs.map((sub) => (
-                                            <li className={clsx("wg_navigationToc__subItem")} 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>
-    );
-};