feat: 홈이 주제를 탭으로 나란히 세운다

홈은 주제 하나만 펴 두고 나머지는 비교 목록 밑 「다른 주제 N개 보기」 한 줄로 보냈다.
그 줄은 목록을 다 읽고 나서야 만나는 자리라 대개 지나쳤고, 그래서 JPA 주제는 홈에
있으면서도 없는 것과 같았다.

구역 제목이 서 있던 자리(「구조별로 알게 된 것」)를 주제 이름 탭이 대신한다. 무엇이 더
있는지가 목록을 읽기 전에 먼저 보이고, 탭을 고르면 그 주제의 축이 그대로 열린다 —
인증 경계면 SPA·Mediator·BFF·Forward-Auth, JPA면 그 주제의 조회 전략들이다.

- 축의 이름은 목록 바로 위로 내렸다. 제목 자리를 탭이 가져갔으니 「이 넷은 구조다」는
  목록에 붙어 있어야 짝이 보인다.
- 패널은 전부 그려 두고 감춘다. 상세는 이미 받아 온 것이라 탭을 눌러도 요청이 나가지
  않고, 페이지 내 검색이 감춘 주제까지 찾는다.
- 탭이 되는 주제 수에 상한을 둔다. 주제마다 상세 요청이 하나씩 나가므로, 주제가 늘어도
  홈의 요청 수는 정해져 있다.
- 「다른 주제」 줄은 축이 없어 탭이 되지 못한 주제만 받는다.

탭은 h2 가 아니지만 구역 제목의 자리를 물려받았으므로 `section-heading-rank` 가 그 급을
정본과 함께 묶는다.
This commit is contained in:
DongHyeonka
2026-09-02 10:59:14 +09:00
parent fe6b56a96c
commit de4cb8b30b
5 changed files with 375 additions and 71 deletions
@@ -0,0 +1,124 @@
import { useRef, useState } from "react";
import { Link } from "react-router-dom";
import type { PublicTopicDetail } from "../../../application/ports/public-content-queries.ts";
import { moveFocus } from "../../../domain/public/focus-state.ts";
/**
* 홈에서 주제를 갈아 가며 그 안의 비교를 읽는 자리.
*
* <p>예전에는 주제 하나만 펴 두고 나머지는 아래 「다른 주제 N개 보기」 한 줄로 보냈다. 그 줄은
* 비교 목록 밑에 작은 글씨로 있어서, 읽는 사람이 첫 주제를 다 읽고 나서야 만났고 대개 그냥
* 지나쳤다 — 실제로 JPA 주제는 홈에 있는데도 없는 것과 같았다. 주제 이름을 탭으로 나란히 세우면
* 무엇이 더 있는지가 목록을 읽기 전에 먼저 보인다.
*
* <p>패널은 전부 그려 두고 `hidden` 으로 감춘다. 주제 상세는 이미 다 받아 온 것이라 탭을 눌러도
* 요청이 나가지 않고, 브라우저의 페이지 내 검색이 감춘 주제까지 찾아 준다.
*/
export function HomeTopicTabs({
topics,
}: {
topics: ReadonlyArray<PublicTopicDetail>;
}) {
const [activeSlug, setActiveSlug] = useState(topics[0]?.slug ?? "");
const buttons = useRef<Array<HTMLButtonElement | null>>([]);
const slugs = topics.map((topic) => topic.slug);
const active = topics.find((topic) => topic.slug === activeSlug) ?? topics[0];
function select(slug: string, moveKeyboardFocus = false) {
setActiveSlug(slug);
if (moveKeyboardFocus) {
requestAnimationFrame(() => {
buttons.current[slugs.indexOf(slug)]?.focus();
});
}
}
function onKeyDown(event: React.KeyboardEvent<HTMLButtonElement>) {
if (!["ArrowLeft", "ArrowRight", "Home", "End"].includes(event.key)) return;
event.preventDefault();
const next = moveFocus(active?.slug ?? "", event.key, slugs);
if (next) select(next, true);
}
if (!active) return null;
return (
<>
{/*
탭이 하나뿐이면 고를 것이 없다. 그래도 주제 이름은 보여야 한다 — 아래 목록이 무엇을
견준 것인지 말해 주는 유일한 자리이기 때문이다. 그래서 목록은 지우지 않고, 고르는
일만 없앤다.
*/}
<div
className="home-topic-tabs"
role={topics.length > 1 ? "tablist" : undefined}
aria-label={topics.length > 1 ? "주제 고르기" : undefined}
>
{topics.map((topic, index) => {
const selected = topic.slug === active.slug;
return (
<button
key={topic.slug}
ref={(button) => {
buttons.current[index] = button;
}}
id={`home-topic-tab-${topic.slug}`}
type="button"
role={topics.length > 1 ? "tab" : undefined}
aria-selected={topics.length > 1 ? selected : undefined}
aria-controls={`home-topic-panel-${topic.slug}`}
tabIndex={topics.length > 1 && !selected ? -1 : 0}
onClick={() => select(topic.slug)}
onKeyDown={onKeyDown}
>
{topic.name}
</button>
);
})}
</div>
{topics.map((topic) => {
const axisLabel = topic.variantLabel.trim();
return (
<div
key={topic.slug}
id={`home-topic-panel-${topic.slug}`}
className="home-topic-panel"
role={topics.length > 1 ? "tabpanel" : undefined}
aria-labelledby={
topics.length > 1 ? `home-topic-tab-${topic.slug}` : undefined
}
hidden={topic.slug !== active.slug}
>
{/*
무엇을 기준으로 나눈 목록인지 한 낱말로 말한다. 제목 자리를 탭이 가져갔으니 축의
이름은 목록 바로 위에 붙어야 짝이 보인다 — 「구조」 넷과 「조회 전략」 셋은 같은
배치로 그려지지만 다른 것을 견준다.
*/}
<div className="home-topic-axis">
<p className="section-kicker">{axisLabel || "비교"}</p>
<Link className="text-link section-action" to={`/topics/${topic.slug}`}>
{`${topic.name} 전체 보기`}
</Link>
</div>
<ul>
{topic.variants.map((variant) => (
<li key={variant.slug}>
<Link to={variant.path}>
<strong>{variant.title}</strong>
{/*
비교표가 읽는 것은 결론이다. 요약은 이것이 무엇인가를 말하고, 결론은
만들어 보고 무엇을 알게 됐는가를 말한다.
*/}
<p>{variant.conclusion || variant.summary}</p>
</Link>
</li>
))}
</ul>
</div>
);
})}
</>
);
}
@@ -10,6 +10,7 @@ import { useRouteInput } from "../../../../../presentation/routes/route-input.ts
import { usePublicContent } from "../use-public-content.tsx";
import { FatalErrorState } from "../components/fatal-error-state.tsx";
import { HomeFocus } from "../components/home-focus.tsx";
import { HomeTopicTabs } from "../components/home-topic-tabs.tsx";
import {
LatestIndex,
type LatestEntry,
@@ -124,50 +125,44 @@ function dateLabel(isoTimestamp: string): string {
).padStart(2, "0")}`;
}
/** 홈이 탭으로 펴 두는 주제 수. 주제마다 상세 요청이 하나씩 나가므로 상한을 둔다. */
const TOPIC_TABS_ON_HOME = 4;
/**
* 홈이 앞에 세울 주제 하나.
* 홈이 비교를 펴 두는 주제들.
*
* <p>가장 많이 다룬 주제를 고른다 — 기록이 가장 많이 쌓인 곳이 이 기록의 중심이고, 그 주제
* 안에서 무엇을 견줬는지가 방문자가 30초 안에 알아야 할 것이다. 축을 쓰지 않는 주제라면
* 견줄 것이 없으므로 이 구역을 그리지 않는다.
* <p>기록이 많이 쌓인 순으로 세운다 — 앞에 오는 탭이 이 기록의 중심이다. 축을 쓰지 않는
* 주제는 견줄 것이 없으므로 탭이 되지 않고, 주제 목록이 받는다.
*
* <p>요청은 둘이다(목록 하나 + 상세 하나). 주제마다 상세를 부르면 주제 수만큼 늘어난다 —
* 홈의 최근 기록이 프로젝트마다 요청을 보내던 시절에 겪은 것과 같은 모양이다.
* <p>예전에는 첫 주제 하나만 펴 두고 나머지는 아래 한 줄로 보냈다. 그 줄은 비교 목록 밑에
* 작은 글씨로 있어 대개 지나쳤고, 그래서 JPA 주제는 홈에 있으면서도 없는 것과 같았다.
*
* <p>요청은 목록 하나 + 탭이 되는 주제마다 상세 하나다. 주제가 늘어도 상한이 있어 홈의
* 요청 수는 정해져 있다 — 프로젝트마다 요청을 보내던 최근 기록에서 겪은 것과 같은 모양을
* 만들지 않는다.
*/
async function getTopics(publicContent: PublicContentQueries) {
const topics = await publicContent.listTopics();
// 목록의 순서는 서버가 정한다. 「가장 많이 다룬」은 여기서 직접 골라야 하는 것이고,
// 첫 항목을 쓰면 기록 3편짜리 주제가 18편짜리를 제치고 홈에 오른다.
const byWeight = [...topics].sort((left, right) => right.recordCount - left.recordCount);
const featuredSlug = byWeight[0]?.slug;
const detail = featuredSlug ? await publicContent.getTopicDetail(featuredSlug) : undefined;
const comparable = [...topics]
.filter((topic) => topic.variantCount > 1)
.sort((left, right) => right.recordCount - left.recordCount);
const shown = comparable.slice(0, TOPIC_TABS_ON_HOME);
const details = await Promise.all(
shown.map((topic) => publicContent.getTopicDetail(topic.slug)),
);
return {
/** 비교표를 펼쳐 둘 주제. 축이 둘 이상이어야 견줄 것이 있다. */
featured: detail && detail.variants.length > 1 ? detail : null,
/*
나머지 주제. 홈이 주제 하나만 펼쳐 두던 동안 나머지 주제는 최근 기록에 우연히 걸릴 때만
보였고, 그 주제가 무엇을 견줬는지는 어디에도 나오지 않았다 — 실제로 JPA 의 비교표는 홈
어디에서도 닿을 수 없었다.
*/
others: byWeight.filter((topic) => topic.slug !== featuredSlug),
/** 탭 하나씩. 축이 둘 이상이어야 견줄 것이 있다. */
tabs: details.filter(
(detail): detail is PublicTopicDetail =>
detail !== undefined && detail.variants.length > 1,
),
/** 탭에 오르지 못한 주제 수. 있으면 주제 목록으로 가는 길을 남긴다. */
remaining: topics.length - shown.length,
};
}
/**
* 비교 구역의 제목.
*
* <p>「무엇을 견줬나」였다. 의문형 꼬리와, 이 사이트의 다른 문장에 쓰지 않는 낱말이 둘 다
* 걸렸다 — 작성자가 Case 의 소제목에 쓰는 말은 「이 구조에서 감수한 것」·「브라우저에 실제로
* 남는 것」처럼 「~한 것」 명사형이다. 그 목소리에 맞춘다.
*
* <p>주제 이름은 제목에서 뺐다. 아래 「전체 보기」 줄이 그 자리를 맡으므로 em-dash 로 두 가지
* 일을 한 줄에 욱여넣을 이유가 없어졌다.
*/
function comparisonTitle(topic: PublicTopicDetail): string {
const axis = topic.variantLabel.trim();
return axis ? `${axis}별로 알게 된 것` : "같은 기준으로 본 것";
}
export function HomePage() {
const { search } = useRouteInput<"TECH_LOG_HOME">();
const requestedKey = optionalString(search.focus);
@@ -183,7 +178,6 @@ export function HomePage() {
if (!view.ready) return view.fallback;
const { focusItems, latestEntries, topics } = view.data;
const featuredTopic = topics.featured;
const availableFocusItems = requestedState === "focus-empty" ? [] : focusItems;
const normalizedKey = normalizeFocus(
requestedKey,
@@ -224,44 +218,23 @@ export function HomePage() {
30초 안에 알아야 할 것은 「무엇을 만들었나」가 아니라 「무엇을 견줬고 무엇이 남았나」다.
축마다 만들어 보고 무엇을 알게 됐는지(결론)를 나란히 둔다 — 요약을 쓰면 무엇인가만
말하고 무엇을 알게 됐는지는 말하지 않는다.
제목 자리에는 주제 이름들이 탭으로 선다. 「구조별로 알게 된 것」 한 줄이 서 있던 동안
홈이 펴 두는 주제는 하나였고, 나머지로 가는 길은 목록 밑 작은 글씨 한 줄뿐이었다 —
무엇이 더 있는지는 다 읽고 나서야 알 수 있었다. 이름을 나란히 세우면 목록을 읽기
전에 먼저 보인다.
*/}
{featuredTopic ? (
<section className="shell home-comparison" aria-labelledby="home-comparison-title">
{/*
제목 안에 링크를 두지 않는다. 비교 행에 건 격자 규칙이 그 링크까지 잡아 제목이
200px 칸에 갇혀 두 줄로 접혔고, 뒤에 오던 부제만 전체 폭에 한 줄로 떨어져 위계가
뒤집혀 보였다. 주제로 가는 길은 아래 한 줄이 맡는다 — 최근 기록이 이미 쓰는 배치다.
*/}
<div className="section-heading-row">
<div>
<p className="section-kicker">
{featuredTopic.variantLabel.trim() || "Comparison"}
</p>
<h2 id="home-comparison-title">{comparisonTitle(featuredTopic)}</h2>
</div>
<Link className="text-link section-action" to={`/topics/${featuredTopic.slug}`}>
{`${featuredTopic.name} 전체 보기`}
</Link>
</div>
<ul>
{featuredTopic.variants.map((variant) => (
<li key={variant.slug}>
<Link to={variant.path}>
<strong>{variant.title}</strong>
<p>{variant.conclusion || variant.summary}</p>
</Link>
</li>
))}
</ul>
{topics.tabs.length > 0 ? (
<section className="shell home-comparison" aria-label="주제별로 견준 것">
<HomeTopicTabs topics={topics.tabs} />
{/*
나머지 주제로 가는 길. 하나만 펼쳐 두면 그 주제가 이 기록의 전부인 것처럼 보인다 —
실제로 JPA 주제는 최근 기록에 우연히 걸릴 때만 보였다. 여기서 펼치지는 않는다;
견주는 자리는 한 번에 하나여야 읽히고, 나머지는 주제 목록이 받는다.
축을 쓰지 않아 탭이 되지 못한 주제로 가는 길. 탭에 다 올라와 있으면 이 줄은
없다 — 같은 곳으로 가는 길이 둘일 이유가 없다.
*/}
{topics.others.length > 0 ? (
{topics.remaining > 0 ? (
<p className="home-other-topics">
<Link to="/topics">{`다른 주제 ${topics.others.length}개 보기`}</Link>
<Link to="/topics">{`다른 주제 ${topics.remaining}개 보기`}</Link>
</p>
) : null}
</section>
@@ -2964,8 +2964,68 @@ textarea.studio-control { min-height: 118px; resize: vertical; line-height: 1.65
margin-top: 96px;
}
.home-comparison h2 {
margin: 10px 0 0;
/*
주제 이름 탭. 구역 제목이 서 있던 자리라 그 급을 그대로 쓴다 — 크기와 굵기는
`.section-heading-row h2` 를 따른다(`section-heading-rank` 검사가 그 짝을 지킨다).
고르지 않은 탭은 색만 죽인다. 크기를 줄이면 탭이 아니라 「하나가 제목이고 나머지는 곁다리」로
읽히는데, 이 자리에서 하려는 말은 그 반대다 — 주제들은 나란하다.
*/
.home-topic-tabs {
display: flex;
flex-wrap: wrap;
gap: 8px 32px;
padding-bottom: 26px;
}
.home-topic-tabs button {
position: relative;
padding: 11px 0 6px;
border: 0;
background: transparent;
color: var(--faint);
cursor: pointer;
font-family: inherit;
font-size: 30px;
font-weight: 650;
letter-spacing: -0.045em;
line-height: 1.15;
text-align: left;
}
.home-topic-tabs button[aria-selected="true"],
.home-topic-tabs button:only-child {
color: var(--ink);
}
.home-topic-tabs button[aria-selected="true"]::after {
position: absolute;
right: 0;
bottom: 0;
left: 0;
height: 2px;
background: var(--signal);
content: "";
}
.home-topic-tabs button:hover {
color: var(--ink);
}
/*
축 이름과 주제로 가는 길. 목록 바로 위에 붙어야 「이 넷은 구조다」가 읽힌다 — 탭 옆에 두면
탭을 바꿀 때 무엇이 따라 바뀌는지가 보이지 않는다.
*/
.home-topic-axis {
display: flex;
align-items: baseline;
justify-content: space-between;
gap: 24px;
padding-bottom: 10px;
}
.home-topic-axis .section-kicker {
margin: 0;
}
.home-comparison ul {
@@ -3016,6 +3076,15 @@ textarea.studio-control { min-height: 118px; resize: vertical; line-height: 1.65
grid-template-columns: minmax(0, 1fr);
gap: 8px;
}
/* 좁은 화면에서는 탭 이름이 두세 줄로 접힌다 — 나란히 세우려면 급을 한 단 낮춰야 한다. */
.home-topic-tabs {
gap: 6px 22px;
}
.home-topic-tabs button {
font-size: 22px;
}
}
.topic-variants-note {
@@ -3044,8 +3113,8 @@ textarea.studio-control { min-height: 118px; resize: vertical; line-height: 1.65
/*
홈의 「다른 주제」 한 줄. 비교표는 한 번에 한 주제만 펼치되, 나머지가 있다는 사실과 그리로
가는 길은 남긴다 — 하나만 보이면 그 주제가 이 기록의 전부인 것처럼 읽힌다.
홈의 「다른 주제」 한 줄. 축을 쓰는 주제는 전부 탭에 올라오므로, 이 줄이 받는 것은 축이 없어
견줄 것이 없는 주제뿐이다. 탭에 다 있으면 이 줄은 나오지 않는다.
*/
.home-other-topics {
display: flex;
@@ -0,0 +1,131 @@
// @vitest-environment jsdom
import { render, screen, within } from "@testing-library/react";
import userEvent from "@testing-library/user-event";
import { describe, expect, it } from "vitest";
import { MemoryRouter } from "react-router-dom";
import type { PublicTopicDetail } from "../../../src/features/tech-log/application/ports/public-content-queries.ts";
import { HomeTopicTabs } from "../../../src/features/tech-log/presentation/public/components/home-topic-tabs.tsx";
/**
* 홈이 주제 하나만 펴 두던 동안, 나머지로 가는 길은 비교 목록 밑의 작은 글씨 한 줄뿐이었다 —
* 다 읽고 나서야 만나는 자리라 대개 지나쳤다. 탭이 하는 일은 「무엇이 더 있는지」를 목록보다
* 먼저 보이게 하는 것이므로, 검사도 그것을 본다.
*/
function topic(
slug: string,
name: string,
variantLabel: string,
variants: ReadonlyArray<[string, string, string]>,
): PublicTopicDetail {
return {
name,
slug,
description: "",
thesis: "",
variantLabel,
variants: variants.map(([variantSlug, title, conclusion]) => ({
slug: variantSlug,
title,
path: `/topics/${slug}/${variantSlug}`,
summary: `${title} 요약`,
conclusion,
recordCount: 2,
})),
featuredCases: [],
activeQuestions: [],
relatedProjects: [],
};
}
const AUTH = topic("oauth-oidc-auth-boundary", "OAuth/OIDC 인증 경계", "구조", [
["spa", "SPA", "브라우저가 token 을 들고 있다"],
["mediator", "Mediator", "교환만 서버가 맡는다"],
["bff", "BFF", "서버가 세션을 갖는다"],
["forward-auth", "Forward-Auth", "게이트웨이가 신원을 붙인다"],
]);
const JPA = topic("jpa-feed-query-performance", "JPA 피드 조회 성능", "조회 전략", [
["fetch-join", "Fetch Join", "행이 곱해진다"],
["derived-query", "Derived Query", "쿼리가 나뉜다"],
]);
function renderTabs(topics: ReadonlyArray<PublicTopicDetail>) {
return render(
<MemoryRouter>
<HomeTopicTabs topics={topics} />
</MemoryRouter>,
);
}
describe("홈의 주제 탭", () => {
it("주제 이름이 목록보다 먼저 전부 보인다", () => {
renderTabs([AUTH, JPA]);
expect(screen.getAllByRole("tab").map((tab) => tab.textContent)).toEqual([
"OAuth/OIDC 인증 경계",
"JPA 피드 조회 성능",
]);
});
it("첫 주제의 축이 열려 있고 나머지 주제의 축은 감춰져 있다", () => {
renderTabs([AUTH, JPA]);
const open = screen.getByRole("tabpanel");
expect(within(open).getAllByRole("link").map((link) => link.textContent)).toEqual([
"OAuth/OIDC 인증 경계 전체 보기",
"SPA브라우저가 token 을 들고 있다",
"Mediator교환만 서버가 맡는다",
"BFF서버가 세션을 갖는다",
"Forward-Auth게이트웨이가 신원을 붙인다",
]);
expect(within(open).getByText("구조")).toBeTruthy();
});
it("탭을 고르면 그 주제의 축으로 바뀐다", async () => {
const user = userEvent.setup();
renderTabs([AUTH, JPA]);
await user.click(screen.getByRole("tab", { name: "JPA 피드 조회 성능" }));
const open = screen.getByRole("tabpanel");
expect(within(open).getByText("조회 전략")).toBeTruthy();
expect(
within(open)
.getAllByRole("link")
.map((link) => link.getAttribute("href")),
).toEqual([
"/topics/jpa-feed-query-performance",
"/topics/jpa-feed-query-performance/fetch-join",
"/topics/jpa-feed-query-performance/derived-query",
]);
});
it("방향키로 탭을 옮긴다", async () => {
const user = userEvent.setup();
renderTabs([AUTH, JPA]);
await user.tab();
await user.keyboard("{ArrowRight}");
expect(screen.getByRole("tab", { selected: true }).textContent).toBe(
"JPA 피드 조회 성능",
);
});
it("주제가 하나면 고를 것이 없지만 목록은 그대로 나온다", () => {
renderTabs([AUTH]);
expect(screen.queryAllByRole("tab")).toHaveLength(0);
expect(screen.getByRole("button").textContent).toBe("OAuth/OIDC 인증 경계");
expect(
screen.getAllByRole("link").map((link) => link.getAttribute("href")),
).toEqual([
"/topics/oauth-oidc-auth-boundary",
"/topics/oauth-oidc-auth-boundary/spa",
"/topics/oauth-oidc-auth-boundary/mediator",
"/topics/oauth-oidc-auth-boundary/bff",
"/topics/oauth-oidc-auth-boundary/forward-auth",
]);
});
});
@@ -17,11 +17,18 @@ const RAW = readFileSync("src/features/tech-log/presentation/styles/globals.css"
*/
const CSS = RAW.replace(/@media[^{]*\{(?:[^{}]*\{[^}]*\})*[^{}]*\}/gu, "");
/** 나란히 서는 구역 제목들. 정본이 맨 앞이다. */
/**
* 나란히 서는 구역 제목들. 정본이 맨 앞이다.
*
* <p>홈의 주제 탭은 h2 가 아니지만 구역 제목이 서 있던 자리를 그대로 물려받았다. 태그가 다르다는
* 이유로 급을 따로 정하면 같은 자리에 있는 글자가 화면마다 다른 크기로 나온다 — 이 검사가 처음
* 잡은 것이 바로 그 일이다.
*/
const SECTION_HEADINGS = [
".section-heading-row h2",
".document-relations h2",
".topic-variants h2",
".home-topic-tabs button",
] as const;
/** 마지막으로 선언된 값을 읽는다 — 뒤에 오는 규칙이 이긴다. */