for-humanity 0.1.0

package/src/component/widget/shell/_function/to-toc-groups.ts

@@ -0,0 +1,38 @@
+import {takeWhile} from "es-toolkit/array";
+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";
+
+/**
+ * h2별 h3 수집 · 가름 시작 절에서 목차 묶음 분리
+ * 첫 h2 앞의 h3은 목차 제외
+ */
+export const toTocGroups = (outline: DocOutline): TocGroup[] => {
+    const entries = outline.headings
+        .filter((heading) => heading.depth === section_heading_depth.section || heading.depth === section_heading_depth.sub)
+        .map((heading, index) => ({heading, section: outline.sections[index]}));
+    const sections = entries.flatMap((entry, index): TocSection[] =>
+        entry.heading.depth === section_heading_depth.section
+            ? [
+                  {
+                      heading: entry.heading,
+                      part: entry.section.part,
+                      subs: takeWhile(entries.slice(index + 1), (sub) => sub.heading.depth !== section_heading_depth.section).map((sub) => ({
+                          heading: sub.heading,
+                      })),
+                  },
+              ]
+            : [],
+    );
+
+    return sections.flatMap((section, index) =>
+        index === 0 || section.part !== undefined
+            ? [
+                  {
+                      part: section.part,
+                      sections: [section, ...takeWhile(sections.slice(index + 1), (next) => next.part === undefined)],
+                  },
+              ]
+            : [],
+    );
+};

package/src/component/widget/shell/_type/doc-outline.ts

@@ -0,0 +1,16 @@
+import type {DocSection} from "@/component/widget/prose/_type/doc-section";
+import type {DocHeading} from "@/type/doc-heading";
+
+/**
+ * 문서 렌더링 결과의 목차 입력
+ */
+export interface DocOutline {
+    /**
+     * 작성한 제목의 id와 텍스트 · 문서 순서
+     */
+    headings: DocHeading[];
+    /**
+     * 제목별 가름 · headings의 h2·h3 순서와 일치
+     */
+    sections: DocSection[];
+}

package/src/component/widget/shell/_type/toc-group.ts

@@ -0,0 +1,39 @@
+import type {DocHeading} from "@/type/doc-heading";
+
+/**
+ * 목차 소제목 항목
+ */
+export interface TocSub {
+    /**
+     * 제목 id와 텍스트
+     */
+    heading: DocHeading;
+}
+
+/**
+ * 목차 절과 소제목 목록
+ */
+export interface TocSection extends TocSub {
+    /**
+     * 이 절에서 시작하는 가름 이름
+     */
+    part?: string;
+    /**
+     * 해당 절의 소제목 · 현재 위치와 무관하게 전체 표시
+     */
+    subs: TocSub[];
+}
+
+/**
+ * 가름별 목차 묶음 · 첫 묶음 이름 생략 가능
+ */
+export interface TocGroup {
+    /**
+     * 묶음 위의 가름 이름
+     */
+    part?: string;
+    /**
+     * 묶음의 절 목록
+     */
+    sections: TocSection[];
+}

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

@@ -0,0 +1,134 @@
+/*
+ * 읽는 순서의 문서 목록 · 중립색 1px 트리
+ */
+.wg_shellNav__root {
+    font-size: var(--app-font-size-dense);
+    line-height: var(--app-line-height-tight);
+}
+
+.wg_shellNav__docs {
+    display: flex;
+    flex-direction: column;
+    gap: var(--app-space-stack);
+}
+
+.wg_shellNav__list {
+    margin: 0 0 0 var(--app-space-tree-inset);
+    padding: 0;
+    list-style: none;
+}
+
+.wg_shellNav__item {
+    /* 세로 줄기는 각 항목 기준 · 마지막 항목의 첫 줄 가운데에서 종료 */
+    position: relative;
+
+    &::before {
+        position: absolute;
+        top: 0;
+        bottom: 0;
+        left: 0;
+        border-left: 1px solid var(--app-color-border-soft);
+        content: "";
+        pointer-events: none;
+    }
+
+    &:where(:last-child)::before {
+        bottom: auto;
+        height: calc(0.5lh + var(--app-space-tree-row));
+    }
+
+    /* hover·키보드 포커스의 도착점 · 첫 줄 아래는 기본 줄기 유지 */
+    &::after {
+        position: absolute;
+        top: 0;
+        left: 0;
+        height: calc(0.5lh + var(--app-space-tree-row));
+        border-left: 1px solid transparent;
+        content: "";
+        pointer-events: none;
+    }
+
+    &:where(:hover)::after {
+        border-left-color: var(--app-color-text-strong);
+    }
+
+    &:where(:has(:focus-visible))::after {
+        border-left-color: var(--app-color-text-strong);
+    }
+
+    /* 뒤 항목까지의 세로 경로 · 같은 목록의 형제 안에서만 연결 */
+    &:where(:has(~ .wg_shellNav__item:hover))::before {
+        border-left-color: var(--app-color-text-strong);
+    }
+
+    &:where(:has(~ .wg_shellNav__item :focus-visible))::before {
+        border-left-color: var(--app-color-text-strong);
+    }
+}
+
+.wg_shellNav__item--trail {
+    &::before {
+        border-left-color: var(--app-color-text-strong);
+    }
+}
+
+.wg_shellNav__item--current {
+    &::after {
+        border-left-color: var(--app-color-text-strong);
+    }
+}
+
+.wg_shellNav__link {
+    /* 가로 가지는 링크 첫 줄 기준 · 여러 줄 제목에서도 연결 위치 유지 */
+    position: relative;
+    display: block;
+    padding: var(--app-space-tree-row) 0 var(--app-space-tree-row) calc(var(--app-space-tree-indent) + var(--app-space-inline));
+    color: var(--app-color-text);
+    font-size: var(--app-font-size-dense);
+    line-height: var(--app-line-height-tight);
+    text-decoration: none;
+
+    &::before {
+        position: absolute;
+        top: calc(0.5lh + var(--app-space-tree-row));
+        left: 0;
+        width: var(--app-space-tree-indent);
+        border-top: 1px solid var(--app-color-border-soft);
+        content: "";
+        pointer-events: none;
+    }
+
+    &:where(:hover) {
+        text-decoration: underline;
+    }
+
+    &:where(:hover)::before {
+        border-top-color: currentcolor;
+    }
+
+    /* hover와 같은 밑줄·가지선으로 키보드 위치 표시 */
+    &:where(:focus-visible) {
+        outline: none;
+        text-decoration: underline;
+    }
+
+    &:where(:focus-visible)::before {
+        border-top-color: currentcolor;
+    }
+}
+
+.wg_shellNav__link--active {
+    color: var(--app-color-text-strong);
+    font-weight: var(--app-font-weight-active);
+
+    &::before {
+        border-top-color: currentcolor;
+    }
+}
+
+.wg_shellNav__group {
+    margin: 0 0 4px;
+    color: var(--app-color-text-muted);
+    font-size: var(--app-font-size-label);
+    text-box: trim-start cap alphabetic;
+}

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

@@ -0,0 +1,75 @@
+import clsx from "clsx";
+import {copy_nav_aria_label} from "@/constant/copy";
+import {toDocGroups} from "@/content/to-doc-groups";
+import type {Doc} from "@/type/doc";
+import type {SiteConfig} from "@/type/site-config";
+import "./_wg-shell-nav.css";
+
+/**
+ * 서버 사이드바 입력 · 읽는 순서의 문서 묶음
+ */
+export interface WgShellNavProps {
+    /**
+     * 문서 묶음 순서
+     */
+    site: SiteConfig;
+    /**
+     * 전체 문서 목록
+     */
+    docs: Doc[];
+    /**
+     * 현재 문서 id · 첫 화면 생략
+     */
+    current?: string;
+}
+
+export const WgShellNav = (props: WgShellNavProps) => {
+    const docGroups = toDocGroups({docs: props.docs, navigation: props.site.navigation});
+
+    return (
+        <nav className={clsx("wg_shellNav__root")} aria-label={copy_nav_aria_label}>
+            {/**
+             * 문서 이동 · 독자 목적별 묶음
+             */}
+            <div className={clsx("wg_shellNav__docs")}>
+                {/**
+                 * 묶음 이름과 독립 문서 · 제목이 링크의 접근 가능한 이름
+                 */}
+                {docGroups.map((group) => {
+                    const currentIndex = group.docs.findIndex((doc) => doc.id === props.current);
+
+                    return (
+                        <section className={clsx("wg_shellNav__docGroup")} key={group.name} aria-label={group.name}>
+                            <div className={clsx("wg_shellNav__group")}>{group.name}</div>
+                            {/**
+                             * 현재 문서와 묶음 시작부터 이어지는 세로 경로 표시
+                             */}
+                            <ul className={clsx("wg_shellNav__list")}>
+                                {group.docs.map((doc, index) => (
+                                    <li
+                                        className={clsx("wg_shellNav__item", {
+                                            "wg_shellNav__item--trail": index < currentIndex,
+                                            "wg_shellNav__item--current": index === currentIndex,
+                                        })}
+                                        key={doc.id}
+                                    >
+                                        <a
+                                            className={clsx("wg_shellNav__link", {
+                                                "wg_shellNav__link--active": index === currentIndex,
+                                            })}
+                                            href={`/${doc.id}/`}
+                                            title={doc.data.label}
+                                            aria-current={index === currentIndex ? "page" : undefined}
+                                        >
+                                            {doc.data.name}
+                                        </a>
+                                    </li>
+                                ))}
+                            </ul>
+                        </section>
+                    );
+                })}
+            </div>
+        </nav>
+    );
+};

package/src/component/widget/shell/_wg-shell-toc.css

@@ -0,0 +1,268 @@
+/*
+ * 문서 탐색 아래 목차 · 작성한 제목과 계층을 유지하는 중립색 트리
+ */
+.wg_shellToc__root {
+    margin-top: var(--app-space-group);
+    padding-top: var(--app-space-group);
+    border-top: 1px solid var(--app-color-border-soft);
+    font-size: var(--app-font-size-dense);
+    line-height: var(--app-line-height-tight);
+}
+
+.wg_shellToc__label {
+    margin-bottom: var(--app-space-inline);
+    color: var(--app-color-text-muted);
+    font-size: var(--app-font-size-label);
+    font-weight: var(--app-font-weight-mark);
+    letter-spacing: var(--app-letter-spacing-label);
+}
+
+.wg_shellToc__group {
+    margin: var(--app-space-stack) 0 4px;
+    color: var(--app-color-text-muted);
+    font-size: var(--app-font-size-label);
+}
+
+.wg_shellToc__list {
+    margin: 0 0 0 var(--app-space-tree-inset);
+    padding: 0;
+    list-style: none;
+}
+
+.wg_shellToc__link {
+    /* 가로 가지는 링크 첫 줄 기준 · 여러 줄 제목에서도 연결 위치 유지 */
+    position: relative;
+    display: block;
+    padding: var(--app-space-tree-row) 0 var(--app-space-tree-row) calc(var(--app-space-tree-indent) + var(--app-space-inline));
+    color: var(--app-color-text-muted);
+    font-size: var(--app-font-size-dense);
+    line-height: var(--app-line-height-tight);
+    text-decoration: none;
+
+    &::before {
+        position: absolute;
+        top: calc(0.5lh + var(--app-space-tree-row));
+        left: 0;
+        width: var(--app-space-tree-indent);
+        border-top: 1px solid var(--app-color-border-soft);
+        content: "";
+        pointer-events: none;
+    }
+
+    &:where(:hover) {
+        color: var(--app-color-text-strong);
+        text-decoration: underline;
+    }
+
+    &:where(:hover)::before {
+        border-top-color: currentcolor;
+    }
+
+    /* 박스 대신 hover와 같은 진한 글·밑줄·가지선으로 키보드 위치 표시 */
+    &:where(:focus-visible) {
+        outline: none;
+        color: var(--app-color-text-strong);
+        text-decoration: underline;
+    }
+
+    &:where(:focus-visible)::before {
+        border-top-color: currentcolor;
+    }
+}
+
+.wg_shellToc__link--active {
+    color: var(--app-color-text-strong);
+    font-weight: var(--app-font-weight-active);
+
+    &::before {
+        border-top-color: currentcolor;
+    }
+}
+
+.wg_shellToc__item {
+    /* 하위 목록의 margin을 포함해 다음 항목까지 줄기 연결 */
+    display: flow-root;
+
+    /* 세로 줄기는 항목 전체 기준 · 중간 항목의 소제목 옆에서도 연결 */
+    position: relative;
+
+    &::before {
+        position: absolute;
+        top: 0;
+        bottom: 0;
+        left: 0;
+        border-left: 1px solid var(--app-color-border-soft);
+        content: "";
+        pointer-events: none;
+    }
+
+    &:where(:last-child)::before {
+        bottom: auto;
+        height: calc(0.5lh + var(--app-space-tree-row));
+    }
+
+    /* hover·키보드 포커스의 도착점 · 첫 줄 아래는 기본 줄기 유지 */
+    &::after {
+        position: absolute;
+        top: 0;
+        left: 0;
+        height: calc(0.5lh + var(--app-space-tree-row));
+        border-left: 1px solid transparent;
+        content: "";
+        pointer-events: none;
+    }
+
+    &:where(:hover)::after {
+        border-left-color: var(--app-color-text-strong);
+    }
+
+    &:where(:has(:focus-visible))::after {
+        border-left-color: var(--app-color-text-strong);
+    }
+
+    /* 뒤 항목까지의 세로 경로 · 같은 목록의 형제 안에서만 연결 */
+    &:where(:has(~ .wg_shellToc__item:hover))::before {
+        border-left-color: var(--app-color-text-strong);
+    }
+
+    &:where(:has(~ .wg_shellToc__item :focus-visible))::before {
+        border-left-color: var(--app-color-text-strong);
+    }
+
+    /* 하위 제목을 탐색할 때 상위 절의 가지도 연결 */
+    &:where(:hover) > .wg_shellToc__link::before {
+        border-top-color: var(--app-color-text-strong);
+    }
+
+    &:where(:has(:focus-visible)) > .wg_shellToc__link::before {
+        border-top-color: var(--app-color-text-strong);
+    }
+}
+
+.wg_shellToc__item--trail {
+    &::before {
+        border-left-color: var(--app-color-text-strong);
+    }
+}
+
+.wg_shellToc__item--current {
+    &::after {
+        border-left-color: var(--app-color-text-strong);
+    }
+}
+
+.wg_shellToc__sub {
+    margin: var(--app-space-tree-row) 0 4px var(--app-space-tree-indent);
+    padding: 0;
+    list-style: none;
+}
+
+.wg_shellToc__subItem {
+    /* 하위 줄기는 소제목 항목 기준 · 마지막 소제목 첫 줄에서 종료 */
+    position: relative;
+
+    &::before {
+        position: absolute;
+        top: 0;
+        bottom: 0;
+        left: 0;
+        border-left: 1px solid var(--app-color-border-soft);
+        content: "";
+        pointer-events: none;
+    }
+
+    &:where(:last-child)::before {
+        bottom: auto;
+        height: calc(0.5lh + var(--app-space-tree-row));
+    }
+
+    /* hover·키보드 포커스의 도착점 · 첫 줄 아래는 기본 줄기 유지 */
+    &::after {
+        position: absolute;
+        top: 0;
+        left: 0;
+        height: calc(0.5lh + var(--app-space-tree-row));
+        border-left: 1px solid transparent;
+        content: "";
+        pointer-events: none;
+    }
+
+    &:where(:hover)::after {
+        border-left-color: var(--app-color-text-strong);
+    }
+
+    &:where(:has(:focus-visible))::after {
+        border-left-color: var(--app-color-text-strong);
+    }
+
+    /* 뒤 항목까지의 세로 경로 · 같은 목록의 형제 안에서만 연결 */
+    &:where(:has(~ .wg_shellToc__subItem:hover))::before {
+        border-left-color: var(--app-color-text-strong);
+    }
+
+    &:where(:has(~ .wg_shellToc__subItem :focus-visible))::before {
+        border-left-color: var(--app-color-text-strong);
+    }
+}
+
+.wg_shellToc__subItem--trail {
+    &::before {
+        border-left-color: var(--app-color-text-strong);
+    }
+}
+
+.wg_shellToc__subItem--current {
+    &::after {
+        border-left-color: var(--app-color-text-strong);
+    }
+}
+
+.wg_shellToc__subLink {
+    /* 하위 가지도 링크 첫 줄 기준 · 줄바꿈된 제목 옆으로 선이 늘어나지 않음 */
+    position: relative;
+    display: block;
+    padding: var(--app-space-tree-row) 0 var(--app-space-tree-row) calc(var(--app-space-tree-indent) + var(--app-space-inline));
+    color: var(--app-color-text-muted);
+    font-size: var(--app-font-size-detail);
+    line-height: var(--app-line-height-tight);
+    text-decoration: none;
+
+    &::before {
+        position: absolute;
+        top: calc(0.5lh + var(--app-space-tree-row));
+        left: 0;
+        width: var(--app-space-tree-indent);
+        border-top: 1px solid var(--app-color-border-soft);
+        content: "";
+        pointer-events: none;
+    }
+
+    &:where(:hover) {
+        color: var(--app-color-text-strong);
+        text-decoration: underline;
+    }
+
+    &:where(:hover)::before {
+        border-top-color: currentcolor;
+    }
+
+    /* 상위 목차와 같은 키보드 표현 */
+    &:where(:focus-visible) {
+        outline: none;
+        color: var(--app-color-text-strong);
+        text-decoration: underline;
+    }
+
+    &:where(:focus-visible)::before {
+        border-top-color: currentcolor;
+    }
+}
+
+.wg_shellToc__subLink--active {
+    color: var(--app-color-text-strong);
+    font-weight: var(--app-font-weight-active);
+
+    &::before {
+        border-top-color: currentcolor;
+    }
+}

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

@@ -0,0 +1,57 @@
+import clsx from "clsx";
+import {Fragment} from "react";
+import type {TocGroup} from "@/component/widget/shell/_type/toc-group";
+import {copy_nav_toc_label} from "@/constant/copy";
+import "./_wg-shell-toc.css";
+
+/**
+ * 문서 탐색 아래의 현재 문서 목차 · client.ts에서 읽는 위치 표시
+ */
+export interface WgShellTocProps {
+    /**
+     * 본문 순서의 가름·절·소제목 · 전체 펼침
+     */
+    groups: TocGroup[];
+}
+
+export const WgShellToc = (props: WgShellTocProps) => {
+    return (
+        <nav className={clsx("wg_shellToc__root")} aria-label={copy_nav_toc_label}>
+            <div className={clsx("wg_shellToc__label")}>{copy_nav_toc_label}</div>
+            {/**
+             * 가름별 제목 이동 · 작성한 제목을 본문과 동일하게 표시
+             */}
+            {props.groups.map((group) => (
+                <Fragment key={group.sections[0].heading.slug}>
+                    {group.part !== undefined && <div className={clsx("wg_shellToc__group")}>{group.part}</div>}
+                    {/**
+                     * 현재 위치와 무관하게 모든 소제목 표시
+                     */}
+                    <ul className={clsx("wg_shellToc__list")}>
+                        {group.sections.map((section) => (
+                            <li className={clsx("wg_shellToc__item")} key={section.heading.slug}>
+                                <a className={clsx("wg_shellToc__link")} href={`#${section.heading.slug}`} data-toc-link="">
+                                    {section.heading.text}
+                                </a>
+                                {/**
+                                 * 소제목의 들여쓰기 · JavaScript 없이도 제목 이동 가능
+                                 */}
+                                {section.subs.length > 0 && (
+                                    <ul className={clsx("wg_shellToc__sub")}>
+                                        {section.subs.map((sub) => (
+                                            <li className={clsx("wg_shellToc__subItem")} key={sub.heading.slug}>
+                                                <a className={clsx("wg_shellToc__subLink")} href={`#${sub.heading.slug}`} data-toc-sub-link="">
+                                                    {sub.heading.text}
+                                                </a>
+                                            </li>
+                                        ))}
+                                    </ul>
+                                )}
+                            </li>
+                        ))}
+                    </ul>
+                </Fragment>
+            ))}
+        </nav>
+    );
+};