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 ? "tablist" : undefined} + aria-label={topics.length > 1 ? "주제 고르기" : undefined} + > + {topics.map((topic, index) => { + const selected = topic.slug === active.slug; + return ( + + ); + })} +
+ + {topics.map((topic) => { + const axisLabel = topic.variantLabel.trim(); + return ( +
1 ? "tabpanel" : undefined} + aria-labelledby={ + topics.length > 1 ? `home-topic-tab-${topic.slug}` : undefined + } + hidden={topic.slug !== active.slug} + > + {/* + 무엇을 기준으로 나눈 목록인지 한 낱말로 말한다. 제목 자리를 탭이 가져갔으니 축의 + 이름은 목록 바로 위에 붙어야 짝이 보인다 — 「구조」 넷과 「조회 전략」 셋은 같은 + 배치로 그려지지만 다른 것을 견준다. + */} +
+

{axisLabel || "비교"}

+ + {`${topic.name} 전체 보기`} + +
+ +
+ ); + })} + + ); +} 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 칸에 갇혀 두 줄로 접혔고, 뒤에 오던 부제만 전체 폭에 한 줄로 떨어져 위계가 - 뒤집혀 보였다. 주제로 가는 길은 아래 한 줄이 맡는다 — 최근 기록이 이미 쓰는 배치다. - */} -
-
-

- {featuredTopic.variantLabel.trim() || "Comparison"} -

-

{comparisonTitle(featuredTopic)}

-
- - {`${featuredTopic.name} 전체 보기`} - -
- + {topics.tabs.length > 0 ? ( +
+ {/* - 나머지 주제로 가는 길. 하나만 펼쳐 두면 그 주제가 이 기록의 전부인 것처럼 보인다 — - 실제로 JPA 주제는 최근 기록에 우연히 걸릴 때만 보였다. 여기서 펼치지는 않는다; - 견주는 자리는 한 번에 하나여야 읽히고, 나머지는 주제 목록이 받는다. + 축을 쓰지 않아 탭이 되지 못한 주제로 가는 길. 탭에 다 올라와 있으면 이 줄은 + 없다 — 같은 곳으로 가는 길이 둘일 이유가 없다. */} - {topics.others.length > 0 ? ( + {topics.remaining > 0 ? (

- {`다른 주제 ${topics.others.length}개 보기`} + {`다른 주제 ${topics.remaining}개 보기`}

) : 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; /** 마지막으로 선언된 값을 읽는다 — 뒤에 오는 규칙이 이긴다. */