diff --git a/src/features/tech-log/presentation/public/components/home-topic-tabs.tsx b/src/features/tech-log/presentation/public/components/home-topic-tabs.tsx
new file mode 100644
index 0000000..738c7f6
--- /dev/null
+++ b/src/features/tech-log/presentation/public/components/home-topic-tabs.tsx
@@ -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";
+
+/**
+ * 홈에서 주제를 갈아 가며 그 안의 비교를 읽는 자리.
+ *
+ *
예전에는 주제 하나만 펴 두고 나머지는 아래 「다른 주제 N개 보기」 한 줄로 보냈다. 그 줄은
+ * 비교 목록 밑에 작은 글씨로 있어서, 읽는 사람이 첫 주제를 다 읽고 나서야 만났고 대개 그냥
+ * 지나쳤다 — 실제로 JPA 주제는 홈에 있는데도 없는 것과 같았다. 주제 이름을 탭으로 나란히 세우면
+ * 무엇이 더 있는지가 목록을 읽기 전에 먼저 보인다.
+ *
+ *
패널은 전부 그려 두고 `hidden` 으로 감춘다. 주제 상세는 이미 다 받아 온 것이라 탭을 눌러도
+ * 요청이 나가지 않고, 브라우저의 페이지 내 검색이 감춘 주제까지 찾아 준다.
+ */
+export function HomeTopicTabs({
+ topics,
+}: {
+ topics: ReadonlyArray;
+}) {
+ const [activeSlug, setActiveSlug] = useState(topics[0]?.slug ?? "");
+ const buttons = useRef>([]);
+ 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) {
+ 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 (
+ <>
+ {/*
+ 탭이 하나뿐이면 고를 것이 없다. 그래도 주제 이름은 보여야 한다 — 아래 목록이 무엇을
+ 견준 것인지 말해 주는 유일한 자리이기 때문이다. 그래서 목록은 지우지 않고, 고르는
+ 일만 없앤다.
+ */}
+
1 ? "tabpanel" : undefined}
+ aria-labelledby={
+ topics.length > 1 ? `home-topic-tab-${topic.slug}` : undefined
+ }
+ hidden={topic.slug !== active.slug}
+ >
+ {/*
+ 무엇을 기준으로 나눈 목록인지 한 낱말로 말한다. 제목 자리를 탭이 가져갔으니 축의
+ 이름은 목록 바로 위에 붙어야 짝이 보인다 — 「구조」 넷과 「조회 전략」 셋은 같은
+ 배치로 그려지지만 다른 것을 견준다.
+ */}
+
+
{axisLabel || "비교"}
+
+ {`${topic.name} 전체 보기`}
+
+
+
+ {topic.variants.map((variant) => (
+
+
+ {variant.title}
+ {/*
+ 비교표가 읽는 것은 결론이다. 요약은 이것이 무엇인가를 말하고, 결론은
+ 만들어 보고 무엇을 알게 됐는가를 말한다.
+ */}
+
{variant.conclusion || variant.summary}
+
+
+ ))}
+
+
+ );
+ })}
+ >
+ );
+}
diff --git a/src/features/tech-log/presentation/public/pages/home-page.tsx b/src/features/tech-log/presentation/public/pages/home-page.tsx
index 1acd55c..13580a1 100644
--- a/src/features/tech-log/presentation/public/pages/home-page.tsx
+++ b/src/features/tech-log/presentation/public/pages/home-page.tsx
@@ -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;
+
/**
- * 홈이 앞에 세울 주제 하나.
+ * 홈이 비교를 펴 두는 주제들.
*
- *
가장 많이 다룬 주제를 고른다 — 기록이 가장 많이 쌓인 곳이 이 기록의 중심이고, 그 주제
- * 안에서 무엇을 견줬는지가 방문자가 30초 안에 알아야 할 것이다. 축을 쓰지 않는 주제라면
- * 견줄 것이 없으므로 이 구역을 그리지 않는다.
+ *
기록이 많이 쌓인 순으로 세운다 — 앞에 오는 탭이 이 기록의 중심이다. 축을 쓰지 않는
+ * 주제는 견줄 것이 없으므로 탭이 되지 않고, 주제 목록이 받는다.
*
- *
요청은 둘이다(목록 하나 + 상세 하나). 주제마다 상세를 부르면 주제 수만큼 늘어난다 —
- * 홈의 최근 기록이 프로젝트마다 요청을 보내던 시절에 겪은 것과 같은 모양이다.
+ *
예전에는 첫 주제 하나만 펴 두고 나머지는 아래 한 줄로 보냈다. 그 줄은 비교 목록 밑에
+ * 작은 글씨로 있어 대개 지나쳤고, 그래서 JPA 주제는 홈에 있으면서도 없는 것과 같았다.
+ *
+ *
요청은 목록 하나 + 탭이 되는 주제마다 상세 하나다. 주제가 늘어도 상한이 있어 홈의
+ * 요청 수는 정해져 있다 — 프로젝트마다 요청을 보내던 최근 기록에서 겪은 것과 같은 모양을
+ * 만들지 않는다.
*/
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,
};
}
-/**
- * 비교 구역의 제목.
- *
- *
「무엇을 견줬나」였다. 의문형 꼬리와, 이 사이트의 다른 문장에 쓰지 않는 낱말이 둘 다
- * 걸렸다 — 작성자가 Case 의 소제목에 쓰는 말은 「이 구조에서 감수한 것」·「브라우저에 실제로
- * 남는 것」처럼 「~한 것」 명사형이다. 그 목소리에 맞춘다.
- *
- *
주제 이름은 제목에서 뺐다. 아래 「전체 보기」 줄이 그 자리를 맡으므로 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 ? (
-
- {/*
- 제목 안에 링크를 두지 않는다. 비교 행에 건 격자 규칙이 그 링크까지 잡아 제목이
- 200px 칸에 갇혀 두 줄로 접혔고, 뒤에 오던 부제만 전체 폭에 한 줄로 떨어져 위계가
- 뒤집혀 보였다. 주제로 가는 길은 아래 한 줄이 맡는다 — 최근 기록이 이미 쓰는 배치다.
- */}
-
+ {topics.tabs.length > 0 ? (
+
+
{/*
- 나머지 주제로 가는 길. 하나만 펼쳐 두면 그 주제가 이 기록의 전부인 것처럼 보인다 —
- 실제로 JPA 주제는 최근 기록에 우연히 걸릴 때만 보였다. 여기서 펼치지는 않는다;
- 견주는 자리는 한 번에 하나여야 읽히고, 나머지는 주제 목록이 받는다.
+ 축을 쓰지 않아 탭이 되지 못한 주제로 가는 길. 탭에 다 올라와 있으면 이 줄은
+ 없다 — 같은 곳으로 가는 길이 둘일 이유가 없다.
*/}
- {topics.others.length > 0 ? (
+ {topics.remaining > 0 ? (
) : null}
diff --git a/src/features/tech-log/presentation/styles/globals.css b/src/features/tech-log/presentation/styles/globals.css
index 880c0c3..4c43b41 100644
--- a/src/features/tech-log/presentation/styles/globals.css
+++ b/src/features/tech-log/presentation/styles/globals.css
@@ -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;
diff --git a/tests/features/tech-log/home-topic-tabs.test.tsx b/tests/features/tech-log/home-topic-tabs.test.tsx
new file mode 100644
index 0000000..f6949c3
--- /dev/null
+++ b/tests/features/tech-log/home-topic-tabs.test.tsx
@@ -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) {
+ return render(
+
+
+ ,
+ );
+}
+
+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",
+ ]);
+ });
+});
diff --git a/tests/features/tech-log/section-heading-rank.test.ts b/tests/features/tech-log/section-heading-rank.test.ts
index 324ef0f..52611d3 100644
--- a/tests/features/tech-log/section-heading-rank.test.ts
+++ b/tests/features/tech-log/section-heading-rank.test.ts
@@ -17,11 +17,18 @@ const RAW = readFileSync("src/features/tech-log/presentation/styles/globals.css"
*/
const CSS = RAW.replace(/@media[^{]*\{(?:[^{}]*\{[^}]*\})*[^{}]*\}/gu, "");
-/** 나란히 서는 구역 제목들. 정본이 맨 앞이다. */
+/**
+ * 나란히 서는 구역 제목들. 정본이 맨 앞이다.
+ *
+ *
홈의 주제 탭은 h2 가 아니지만 구역 제목이 서 있던 자리를 그대로 물려받았다. 태그가 다르다는
+ * 이유로 급을 따로 정하면 같은 자리에 있는 글자가 화면마다 다른 크기로 나온다 — 이 검사가 처음
+ * 잡은 것이 바로 그 일이다.
+ */
const SECTION_HEADINGS = [
".section-heading-row h2",
".document-relations h2",
".topic-variants h2",
+ ".home-topic-tabs button",
] as const;
/** 마지막으로 선언된 값을 읽는다 — 뒤에 오는 규칙이 이긴다. */