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' ;
67import Search from ' @astrojs/starlight/components/Search.astro' ;
78import SiteTitle from ' @astrojs/starlight/components/SiteTitle.astro' ;
89import SocialIcons from ' @astrojs/starlight/components/SocialIcons.astro' ;
9- import ThemeSelect from ' @astrojs/starlight/components/ThemeSelect.astro' ;
1010
1111const { 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[] };
2222const 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+
2558const 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 >
0 commit comments