feat: 기록마다 이 조사의 어디쯤인지를 제목 아래에 세운다

이 사이트의 차별점은 "기록 하나에 아무 데서나 들어와도 그 결론을 만든 맥락의 사슬을
잃지 않는다"는 것이다. 그런데 그 사슬이 화면에서는 제목 위 얇은 breadcrumb 한 줄과
문서 맨 아래 「다음에 읽을 것」으로만 표현돼 있었다 — 검색으로 Case 하나에 들어온
사람은 바닥까지 내려가야 이 기록이 어느 프로젝트의 어느 질문에서 나왔는지 알 수
있었다. 저장은 되어 있는데 겪게 되지는 않는 상태였다.

제목·요약 바로 아래에 맥락을 하나의 덩어리로 세운다. 프로젝트 → 주제로 올라가는
길과, 같은 조사 안에서 이웃한 기록들을 함께 보인다. 이웃에는 작성자가 그 관계에 남긴
문장을 붙인다 — 「다음에 무엇을」보다 「왜 그것을」이 먼저 있어야 목록이 아니라 사슬로
읽힌다. 지금 보는 기록도 목록에 남겨 자기 자리가 보이게 한다.

여섯 종류 전부에 들어간다. 종류마다 하나씩 픽스처를 둔 `Record<RecordKind, …>` 검사로
막았다 — 한 종류에서만 빠지면 그 종류로 들어온 방문자에게만 조용히 사슬이 끊긴다.
Question 에서 빼 보고 그 검사만 실패하는 것을 확인했다.

화면 촬영기(`scripts/capture-screens.ts`)도 함께 넣는다. 라우트 레지스트리를 돌며
공개·Studio 전 화면을 찍는다. 찍을 목록을 손으로 적지 않고 `Record<RouteId, …>` 로
두어 라우트가 늘면 컴파일러가 빈 자리를 잡는다.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015c8cBFUaVr7KLVUx6ujz7D
This commit is contained in:
DongHyeonka
2026-09-15 20:03:01 +09:00
co-authored by Claude Opus 5
parent 9e5642cd9f
commit fe1f23520e
11 changed files with 1781 additions and 2 deletions
@@ -0,0 +1,107 @@
import { Link } from "react-router-dom";
import type { components } from "../../../contracts/studio/generated.ts";
import { resolvesToPublicRoute } from "../../../domain/navigation/public-path.ts";
import { DOCUMENT_KIND_LABELS } from "../document-kind-labels.ts";
type PublicRenderModelBase = components["schemas"]["PublicRenderModelBase"];
type ResolvedRelation = components["schemas"]["ResolvedRelation"];
/** 관계 대상의 종류 이름. 프로젝트만 표에 없다 — 기록이 아니라 묶음이기 때문이다. */
function kindLabel(kind: ResolvedRelation["targetKind"]): string {
return kind === "PROJECT" ? "프로젝트" : DOCUMENT_KIND_LABELS[kind];
}
/**
* 이 기록이 어느 조사의 어디쯤인지.
*
* <p>이 사이트의 차별점은 "기록 하나에 아무 데서나 들어와도 그 결론을 만든 맥락의 사슬을 잃지
* 않는다"는 것이다. 그런데 그 사슬이 화면에서는 제목 위 얇은 breadcrumb 한 줄과 문서 맨 아래
* 「다음에 읽을 것」으로만 표현돼 있었다 — 검색으로 Case 하나에 들어온 사람은 바닥까지 내려가야
* 이 기록이 어느 프로젝트의 어느 질문에서 나왔는지 알 수 있었다. 저장은 되어 있는데 겪게 되지는
* 않는 상태였다.
*
* <p>그래서 제목·요약 바로 아래에 맥락을 하나의 덩어리로 세운다. 프로젝트 → 주제까지 올라가는
* 길과, 같은 조사 안에서 이웃한 기록들을 함께 보인다. 지금 보는 기록은 링크가 아니라 현재
* 위치로 표시한다.
*
* <p>이웃 기록에는 작성자가 그 관계에 남긴 문장을 그대로 붙인다. 「다음에 무엇을 읽을지」보다
* 「왜 그것을 읽어야 하는지」가 먼저 있어야 목록이 아니라 사슬로 읽힌다.
*
* <p>`<details>` 하나로 두 폭을 모두 쓴다. 좁은 화면에서는 접을 수 있고, 넓은 화면에서는 CSS 가
* 여는 손잡이를 감춰 늘 펼친 덩어리로 보인다 — 폭을 재서 DOM 을 둘로 만들면 같은 이름의 landmark
* 가 둘이 되어 보조 기술에는 같은 것이 두 번 나온다.
*/
export function ContextNavigator({ model }: { model: PublicRenderModelBase }) {
const project = model.project;
const topic = model.topic.label ? model.topic : null;
/*
열리지 않는 주소는 줄로 그리지 않는다. 게시할 때 만들어 저장한 문자열이라 라우트가 없는
모양이면 화면 코드 어디에도 흔적이 없고 방문자만 404 를 만난다 — 결정의 주소가 실제로 그랬다.
*/
const siblings = [...model.relations]
.filter((relation) => resolvesToPublicRoute(relation.publicPath ?? ""))
.sort((left, right) => left.order - right.order);
// 올라갈 곳도 옆으로 갈 곳도 없으면 맥락이랄 것이 없다. 빈 상자를 남기지 않는다.
if (!project && !topic && siblings.length === 0) return null;
return (
<div className="shell context-navigator-wrap">
<details className="context-navigator" open>
<summary>이 기록의 맥락</summary>
<nav aria-label="이 기록의 맥락">
{project || topic ? (
<ol className="context-trail">
{project ? (
<li>
<span>프로젝트</span>
{project.publicPath ? (
<Link to={project.publicPath}>{project.label}</Link>
) : (
<strong>{project.label}</strong>
)}
</li>
) : null}
{topic ? (
<li>
<span>주제</span>
{topic.publicPath ? (
<Link to={topic.publicPath}>{topic.label}</Link>
) : (
<strong>{topic.label}</strong>
)}
</li>
) : null}
</ol>
) : null}
<ul className="context-siblings">
{/*
지금 보는 기록도 목록에 둔다. 빼 두면 이웃만 나열되어 "내가 그중 어디인가"가 보이지
않는다 — 맥락은 주변이 아니라 자기 자리를 포함해야 위치가 된다.
*/}
<li aria-current="true">
<span className="context-kind">{DOCUMENT_KIND_LABELS[model.kind]}</span>
<div>
<strong>{model.title}</strong>
<p className="context-here">지금 읽는 기록</p>
</div>
</li>
{siblings.map((relation) => (
<li key={relation.id}>
<span className="context-kind">{kindLabel(relation.targetKind)}</span>
<div>
<Link to={relation.publicPath ?? ""}>{relation.title}</Link>
{relation.reason?.trim() ? (
<p className="context-why">{relation.reason}</p>
) : null}
</div>
</li>
))}
</ul>
</nav>
</details>
</div>
);
}
@@ -8,6 +8,7 @@ import type {
ResolvePublishedLabel,
} from "../../../domain/public-render-content.ts";
import { CaseBodyRenderer } from "./case-body-renderer.tsx";
import { ContextNavigator } from "./context-navigator.tsx";
import { DocumentToc } from "./document-toc.tsx";
import {
PublicDocumentRelations,
@@ -218,6 +219,8 @@ function CaseDocument({
</dl>
</header>
<ContextNavigator model={model} />
<DocumentToc headings={headings} variant="mobile" />
<div className="shell document-layout">
@@ -293,6 +296,8 @@ function ConceptDocument({
</dl>
</header>
<ContextNavigator model={model} />
<DocumentToc headings={headings} variant="mobile" />
<div className="shell document-layout">
@@ -380,6 +385,8 @@ function SetupDocument({
</dl>
</header>
<ContextNavigator model={model} />
<DocumentToc headings={headings} variant="mobile" />
<div className="shell document-layout">
@@ -415,6 +422,7 @@ function ReferenceDocument({
model={model}
resolvePublishedLabel={resolvePublishedLabel}
/>
<ContextNavigator model={model} />
<section className="reference-purpose" aria-labelledby="purpose-title">
<p className="section-kicker">Purpose</p>
<h2 id="purpose-title">이 기준을 쓰는 이유</h2>
@@ -508,6 +516,7 @@ function QuestionDocument({
model={model}
resolvePublishedLabel={resolvePublishedLabel}
/>
<ContextNavigator model={model} />
<p
className={`question-status question-status--${model.status.toLowerCase()}`}
>
@@ -598,6 +607,7 @@ function ProjectDecisionDocument({
</>
) : null}
</nav>
<ContextNavigator model={model} />
<ol className="project-decision-list">
<li>
<article id={model.slug}>
@@ -3245,3 +3245,145 @@ textarea.studio-control { min-height: 118px; resize: vertical; line-height: 1.65
text-align: left;
}
}
/* Context Navigator — 이 기록이 어느 조사의 어디쯤인지 */
/*
제목·요약 바로 아래 자리다. 맥락이 breadcrumb 한 줄과 문서 맨 아래 「다음에 읽을 것」에만
있던 동안, 검색으로 기록 하나에 들어온 사람은 바닥까지 내려가야 이 기록이 어디에서 나왔는지
알 수 있었다. 상자를 두르지 않고 왼쪽 선 하나로만 묶는다 — 이 사이트의 나머지 화면이 카드를
쓰지 않는다.
*/
.context-navigator-wrap {
padding-bottom: 8px;
}
.context-navigator {
max-width: 860px;
padding-left: 17px;
border-left: 2px solid var(--line-strong);
}
.context-navigator > summary {
color: var(--muted);
cursor: pointer;
font-size: 12px;
font-weight: 660;
letter-spacing: 0.06em;
list-style: none;
text-transform: uppercase;
}
.context-navigator > summary::-webkit-details-marker {
display: none;
}
.context-navigator > summary::after {
content: " ▾";
}
.context-navigator:not([open]) > summary::after {
content: " ▸";
}
.context-trail {
display: flex;
flex-wrap: wrap;
gap: 8px 26px;
margin: 14px 0 0;
padding: 0;
list-style: none;
}
.context-trail li {
display: flex;
gap: 9px;
align-items: baseline;
}
.context-trail span {
color: var(--faint);
font-size: 12px;
font-weight: 620;
}
.context-trail a,
.context-trail strong {
color: var(--ink);
font-size: 15px;
font-weight: 620;
}
.context-trail a:hover {
color: var(--signal);
}
.context-siblings {
margin: 16px 0 0;
padding: 0;
list-style: none;
}
.context-siblings li {
display: grid;
grid-template-columns: 96px minmax(0, 1fr);
gap: 16px;
padding: 9px 0;
border-top: 1px solid var(--line);
}
.context-siblings li:first-child {
border-top: 0;
}
.context-kind {
color: var(--faint);
font-size: 12px;
font-weight: 620;
line-height: 1.7;
}
.context-siblings a,
.context-siblings strong {
color: var(--ink);
font-size: 15px;
font-weight: 560;
line-height: 1.55;
}
.context-siblings a:hover {
color: var(--signal);
}
/* 지금 보는 기록. 링크가 아니라 현재 위치다. */
.context-siblings li[aria-current] .context-kind,
.context-siblings li[aria-current] strong {
color: var(--signal);
}
.context-here,
.context-why {
margin: 3px 0 0;
color: var(--muted);
font-size: 13px;
line-height: 1.6;
}
.context-here {
color: var(--signal);
font-weight: 560;
}
/* 넓은 화면에서는 접는 손잡이를 감춘다. 늘 펼쳐 둔 덩어리로 읽힌다. */
@media (min-width: 900px) {
.context-navigator > summary {
display: none;
}
}
@media (max-width: 767px) {
.context-siblings li {
grid-template-columns: minmax(0, 1fr);
gap: 3px;
}
}