Skip to content

Commit cc7bb57

Browse files
committed
fix(docs): redesign header preference controls
1 parent d34e8ba commit cc7bb57

2 files changed

Lines changed: 293 additions & 14 deletions

File tree

‎docs-site/src/components/Header.astro‎

Lines changed: 293 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,12 @@
11
---
2-
// Custom Starlight header: default chrome (title / search / social / theme /
3-
// language) plus a desktop-only hover-dropdown nav in the liquid-glass grammar.
2+
// Custom Starlight header: default chrome (title / search / social) plus a
3+
// desktop-only hover-dropdown nav and custom preference controls in the
4+
// liquid-glass grammar.
45
// Mobile (<72rem) hides the nav; the built-in hamburger flow is untouched.
5-
import LanguageSelect from '@astrojs/starlight/components/LanguageSelect.astro';
6+
import { Icon } from '@astrojs/starlight/components';
67
import Search from '@astrojs/starlight/components/Search.astro';
78
import SiteTitle from '@astrojs/starlight/components/SiteTitle.astro';
89
import SocialIcons from '@astrojs/starlight/components/SocialIcons.astro';
9-
import ThemeSelect from '@astrojs/starlight/components/ThemeSelect.astro';
1010
1111
const { locale } = Astro.locals.starlightRoute;
1212
// Splash pages have no Starlight sidebar/hamburger, so the pill carries its own
@@ -22,6 +22,39 @@ type NavGroup = { label: string; links: NavLink[] };
2222
const t = (en: string, ko: string, zh: string, ru: string, ja: string) =>
2323
locale === 'ko' ? ko : locale === 'zh-cn' ? zh : locale === 'ru' ? ru : locale === 'ja' ? ja : en;
2424
25+
type LanguageOption = { code: 'root' | 'ko' | 'zh-cn' | 'ru' | 'ja'; label: string };
26+
const languages: LanguageOption[] = [
27+
{ code: 'root', label: 'English' },
28+
{ code: 'ko', label: '한국어' },
29+
{ code: 'zh-cn', label: '简体中文' },
30+
{ code: 'ru', label: 'Русский' },
31+
{ code: 'ja', label: '日本語' },
32+
];
33+
const currentLanguage = languages.find(({ code }) => code === (locale ?? 'root')) ?? languages[0];
34+
35+
// Preserve the current document path when switching locale. Starlight's root
36+
// locale has no URL segment, while every translated locale does.
37+
const routePrefix = locale ? `${base}${locale}/` : base;
38+
const routeSuffix = Astro.url.pathname.startsWith(routePrefix)
39+
? Astro.url.pathname.slice(routePrefix.length)
40+
: '';
41+
const languageHref = (code: LanguageOption['code']) =>
42+
`${code === 'root' ? base : `${base}${code}/`}${routeSuffix}`;
43+
44+
const themeLabels = {
45+
auto: t('Auto', '자동', '自动', 'Авто', '自動'),
46+
light: t('Light', '라이트', '浅色', 'Светлая', 'ライト'),
47+
dark: t('Dark', '다크', '深色', 'Тёмная', 'ダーク'),
48+
};
49+
const themeName = t('Theme', '테마', '主题', 'Тема', 'テーマ');
50+
const themeCycleHint = t(
51+
'Click to use the next theme',
52+
'클릭하여 다음 테마로 전환',
53+
'点击切换到下一个主题',
54+
'Нажмите, чтобы включить следующую тему',
55+
'クリックして次のテーマに切り替え',
56+
);
57+
2558
const groups: NavGroup[] = [
2659
{
2760
label: t('Getting Started', '시작하기', '开始使用', 'Начало работы', 'はじめに'),
@@ -99,8 +132,64 @@ const contributing: NavLink = {
99132
<div class="sl-flex social-icons">
100133
<SocialIcons />
101134
</div>
102-
<ThemeSelect />
103-
<LanguageSelect />
135+
<div class="sl-flex header-preferences">
136+
{/*
137+
[Decision Log]
138+
- 목적과 의도: Keep theme switching one click away and make locale navigation visually consistent with the site's custom menus.
139+
- 기존 구현 및 제약 조건: Starlight's native selects inherit browser/OS popup styling and mouse focus borders that cannot match the glass design system.
140+
- 검토한 주요 대안: Restyle the native selects; replace both with popovers; cycle theme while keeping language as a popover.
141+
- 선택한 방식: Auto -> Light -> Dark theme cycle button plus a server-rendered language popover.
142+
- 다른 대안 대신 이 방식을 선택한 이유: Native option popups are not fully styleable, and theme has only three predictable states that do not need a menu.
143+
- 장점, 단점 및 영향: Consistent chrome and faster theme changes; the cycle order must remain stable and keyboard focus must remain visible.
144+
*/}
145+
<button
146+
type="button"
147+
class="preference-control theme-cycle"
148+
data-theme-value="auto"
149+
data-auto-label={themeLabels.auto}
150+
data-light-label={themeLabels.light}
151+
data-dark-label={themeLabels.dark}
152+
data-theme-name={themeName}
153+
data-cycle-hint={themeCycleHint}
154+
aria-label={`${themeName}: ${themeLabels.auto}. ${themeCycleHint}`}
155+
title={`${themeName}: ${themeLabels.auto}`}
156+
>
157+
<span class="preference-icon" data-theme-icon="auto"><Icon name="laptop" /></span>
158+
<span class="preference-icon" data-theme-icon="light" hidden><Icon name="sun" /></span>
159+
<span class="preference-icon" data-theme-icon="dark" hidden><Icon name="moon" /></span>
160+
<span data-theme-label>{themeLabels.auto}</span>
161+
</button>
162+
163+
<div class="header-preference language-preference">
164+
<button
165+
type="button"
166+
class="preference-control language-trigger"
167+
aria-haspopup="menu"
168+
aria-expanded="false"
169+
aria-controls="language-menu"
170+
aria-label={t('Select language', '언어 선택', '选择语言', 'Выбрать язык', '言語を選択')}
171+
>
172+
<Icon name="translate" class="preference-icon" />
173+
<span>{currentLanguage.label}</span>
174+
<Icon name="down-caret" class="preference-caret" />
175+
</button>
176+
<div class="language-menu" id="language-menu" role="menu">
177+
<ul>
178+
{languages.map((language) => (
179+
<li>
180+
<a
181+
href={languageHref(language.code)}
182+
role="menuitemradio"
183+
aria-checked={language.code === (locale ?? 'root') ? 'true' : 'false'}
184+
>
185+
{language.label}
186+
</a>
187+
</li>
188+
))}
189+
</ul>
190+
</div>
191+
</div>
192+
</div>
104193
</div>
105194
{isSplash && (
106195
<div class="lp-menu print:hidden">
@@ -170,12 +259,122 @@ const contributing: NavLink = {
170259
gap: 1rem;
171260
align-items: center;
172261
}
262+
.header-preferences {
263+
gap: 0.125rem;
264+
align-items: center;
265+
}
173266
.social-icons::after {
174267
content: '';
175268
height: 2rem;
176269
border-inline-end: 1px solid var(--sl-color-gray-5);
177270
}
178271

272+
/* ---- theme cycle + language popover -------------------------------- */
273+
.header-preference {
274+
position: relative;
275+
}
276+
.preference-control {
277+
display: inline-flex;
278+
align-items: center;
279+
justify-content: center;
280+
gap: 0.375rem;
281+
min-height: 2.25rem;
282+
padding: 0.375rem 0.75rem;
283+
border: 0;
284+
border-radius: var(--ocx-radius-pill, 999px);
285+
background: transparent;
286+
color: var(--sl-color-gray-2);
287+
font: inherit;
288+
font-size: var(--sl-text-sm);
289+
font-weight: 500;
290+
line-height: 1;
291+
white-space: nowrap;
292+
cursor: pointer;
293+
transition: background-color 0.12s, color 0.12s;
294+
}
295+
.preference-control:hover,
296+
.preference-control[aria-expanded='true'] {
297+
background-color: var(--ocx-hover, rgba(128, 128, 128, 0.1));
298+
color: var(--sl-color-white);
299+
}
300+
.preference-control:focus:not(:focus-visible) {
301+
outline: none;
302+
box-shadow: none;
303+
}
304+
.preference-control:focus-visible {
305+
outline: 2px solid color-mix(in srgb, var(--sl-color-accent) 55%, transparent);
306+
outline-offset: 2px;
307+
}
308+
.preference-icon {
309+
display: inline-flex;
310+
font-size: 0.9rem;
311+
}
312+
.preference-icon[hidden] {
313+
display: none;
314+
}
315+
.preference-caret {
316+
font-size: 1rem;
317+
opacity: 0.55;
318+
transition: transform 0.15s ease;
319+
}
320+
.language-trigger[aria-expanded='true'] .preference-caret {
321+
transform: rotate(180deg);
322+
}
323+
.language-menu {
324+
position: absolute;
325+
top: calc(100% + 0.625rem);
326+
inset-inline-end: 0;
327+
min-width: 12rem;
328+
padding: 0.375rem;
329+
border: 1px solid var(--sl-color-gray-5);
330+
border-radius: var(--ocx-radius, 12px);
331+
background-color: var(--ocx-glass-panel, canvas);
332+
backdrop-filter: var(--ocx-glass-blur, blur(22px));
333+
-webkit-backdrop-filter: var(--ocx-glass-blur, blur(22px));
334+
box-shadow: var(--ocx-shadow, 0 10px 28px rgba(0, 0, 0, 0.2));
335+
opacity: 0;
336+
visibility: hidden;
337+
translate: 0 -0.25rem;
338+
transition: opacity 0.16s ease, visibility 0.16s, translate 0.16s ease;
339+
z-index: var(--sl-z-index-navbar);
340+
}
341+
.language-preference:has(> .language-trigger[aria-expanded='true']) .language-menu {
342+
opacity: 1;
343+
visibility: visible;
344+
translate: 0 0;
345+
}
346+
.language-menu ul {
347+
list-style: none;
348+
margin: 0;
349+
padding: 0;
350+
}
351+
.language-menu a {
352+
display: block;
353+
padding: 0.5rem 0.75rem;
354+
border-radius: var(--ocx-radius-sm, 8px);
355+
color: var(--sl-color-gray-2);
356+
font-size: var(--sl-text-sm);
357+
text-decoration: none;
358+
transition: background-color 0.12s, color 0.12s;
359+
}
360+
.language-menu a:hover,
361+
.language-menu a:focus-visible,
362+
.language-menu a[aria-checked='true'] {
363+
background-color: var(--ocx-hover, rgba(128, 128, 128, 0.1));
364+
color: var(--sl-color-white);
365+
}
366+
.language-menu a:focus:not(:focus-visible) {
367+
outline: none;
368+
}
369+
370+
@media (prefers-reduced-motion: reduce) {
371+
.preference-control,
372+
.preference-caret,
373+
.language-menu {
374+
transition: none;
375+
}
376+
}
377+
179378
/* ---- hover-dropdown nav (desktop only) ---- */
180379
.glass-nav {
181380
display: none;
@@ -360,7 +559,9 @@ const contributing: NavLink = {
360559
// Click/Enter/Space toggles the dropdowns (hover and focus-within still work
361560
// via CSS); Escape or an outside click closes any open menu.
362561
const buttons = Array.from(
363-
document.querySelectorAll<HTMLButtonElement>('.glass-nav .nav-link[aria-haspopup], .lp-menu-btn'),
562+
document.querySelectorAll<HTMLButtonElement>(
563+
'.glass-nav .nav-link[aria-haspopup], .lp-menu-btn, .language-trigger',
564+
),
364565
);
365566
const closeAll = (except?: HTMLButtonElement) => {
366567
for (const b of buttons) if (b !== except) b.setAttribute('aria-expanded', 'false');
@@ -373,9 +574,93 @@ const contributing: NavLink = {
373574
});
374575
}
375576
document.addEventListener('click', (e) => {
376-
if (!(e.target instanceof Element) || !e.target.closest('.glass-nav, .lp-menu')) closeAll();
577+
if (!(e.target instanceof Element) || !e.target.closest('.glass-nav, .lp-menu, .header-preference')) closeAll();
377578
});
378579
document.addEventListener('keydown', (e) => {
379580
if (e.key === 'Escape') closeAll();
380581
});
582+
583+
// The theme has three predictable states, so each activation advances the
584+
// stable Auto -> Light -> Dark order instead of opening another menu.
585+
type Theme = 'auto' | 'light' | 'dark';
586+
const themeOrder: Theme[] = ['auto', 'light', 'dark'];
587+
const storageKey = 'starlight-theme';
588+
const preferredTheme = () =>
589+
window.matchMedia('(prefers-color-scheme: light)').matches ? 'light' : 'dark';
590+
const loadTheme = (): Theme => {
591+
const stored = localStorage.getItem(storageKey);
592+
return stored === 'light' || stored === 'dark' ? stored : 'auto';
593+
};
594+
const updateThemeButton = (button: HTMLButtonElement, theme: Theme) => {
595+
const label = button.dataset[`${theme}Label`] ?? theme;
596+
button.dataset.themeValue = theme;
597+
button.querySelector<HTMLElement>('[data-theme-label]')!.textContent = label;
598+
for (const icon of button.querySelectorAll<HTMLElement>('[data-theme-icon]')) {
599+
icon.hidden = icon.dataset.themeIcon !== theme;
600+
}
601+
const themeName = button.dataset.themeName ?? 'Theme';
602+
button.title = `${themeName}: ${label}`;
603+
button.setAttribute('aria-label', `${themeName}: ${label}. ${button.dataset.cycleHint ?? ''}`.trim());
604+
};
605+
const applyTheme = (button: HTMLButtonElement, theme: Theme) => {
606+
document.documentElement.dataset.theme = theme === 'auto' ? preferredTheme() : theme;
607+
localStorage.setItem(storageKey, theme === 'auto' ? '' : theme);
608+
updateThemeButton(button, theme);
609+
};
610+
for (const button of document.querySelectorAll<HTMLButtonElement>('.theme-cycle')) {
611+
applyTheme(button, loadTheme());
612+
button.addEventListener('click', () => {
613+
const current = (button.dataset.themeValue as Theme | undefined) ?? 'auto';
614+
const next = themeOrder[(themeOrder.indexOf(current) + 1) % themeOrder.length] ?? 'auto';
615+
applyTheme(button, next);
616+
});
617+
}
618+
window.matchMedia('(prefers-color-scheme: light)').addEventListener('change', () => {
619+
if (loadTheme() !== 'auto') return;
620+
for (const button of document.querySelectorAll<HTMLButtonElement>('.theme-cycle')) {
621+
applyTheme(button, 'auto');
622+
}
623+
});
624+
625+
// Arrow keys move directly through language links; Escape returns focus to
626+
// the trigger so keyboard navigation behaves like the other header menus.
627+
for (const trigger of document.querySelectorAll<HTMLButtonElement>('.language-trigger')) {
628+
const menu = trigger.parentElement?.querySelector<HTMLElement>('.language-menu');
629+
const items = Array.from(menu?.querySelectorAll<HTMLAnchorElement>('a[role^="menuitem"]') ?? []);
630+
trigger.addEventListener('keydown', (event) => {
631+
if (event.key !== 'ArrowDown' && event.key !== 'ArrowUp') return;
632+
event.preventDefault();
633+
closeAll(trigger);
634+
trigger.setAttribute('aria-expanded', 'true');
635+
const target = items[event.key === 'ArrowDown' ? 0 : items.length - 1];
636+
// The popover intentionally transitions `visibility`; Chromium refuses
637+
// to focus descendants until that transition has made them visible.
638+
const focusWhenVisible = (attempt = 0) => {
639+
if (!target || !menu || trigger.getAttribute('aria-expanded') !== 'true') return;
640+
if (getComputedStyle(menu).visibility === 'visible') {
641+
target.focus();
642+
return;
643+
}
644+
if (attempt < 20) requestAnimationFrame(() => focusWhenVisible(attempt + 1));
645+
};
646+
focusWhenVisible();
647+
});
648+
menu?.addEventListener('keydown', (event) => {
649+
const activeIndex = items.indexOf(document.activeElement as HTMLAnchorElement);
650+
if (event.key === 'Escape') {
651+
event.preventDefault();
652+
trigger.setAttribute('aria-expanded', 'false');
653+
trigger.focus();
654+
return;
655+
}
656+
if (!['ArrowDown', 'ArrowUp', 'Home', 'End'].includes(event.key)) return;
657+
event.preventDefault();
658+
const nextIndex =
659+
event.key === 'Home' ? 0 :
660+
event.key === 'End' ? items.length - 1 :
661+
event.key === 'ArrowDown' ? (activeIndex + 1) % items.length :
662+
(activeIndex - 1 + items.length) % items.length;
663+
items[nextIndex]?.focus();
664+
});
665+
}
381666
</script>

‎docs-site/src/styles/custom.css‎

Lines changed: 0 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -183,12 +183,6 @@ dialog::backdrop {
183183
-webkit-backdrop-filter: blur(6px);
184184
}
185185

186-
/* theme + language selects: pill chrome */
187-
starlight-theme-select select,
188-
starlight-lang-select select {
189-
border-radius: var(--ocx-radius-pill);
190-
}
191-
192186
/* ---- right rail (toc) ---------------------------------------------------- */
193187
.right-sidebar {
194188
border-inline-start: 1px solid var(--sl-color-hairline-light);

0 commit comments

Comments
 (0)