import { FASTElement, Observable, html, css, repeat, when } from '@microsoft/fast-element'; import { pageReset } from '@beatzball/litro/adapter/fast/page-reset'; export interface NavItem { label: string; href: string; } const hamburgerSvg = html` `; const closeSvg = html` `; /** * A real browser, not a server DOM shim. * * `typeof document !== 'undefined'` is NOT enough here. @microsoft/fast-ssr * runs connectedCallback ON THE SERVER, against a document shim that has no * documentElement — so that guard waved the server straight into * `document.documentElement.getAttribute(...)`, which threw * "Cannot read properties of undefined (reading 'getAttribute')" and took * down the SSR stream for every page carrying this header. Lit's SSR never * calls connectedCallback and Elena's never does either, so only FAST broke. * * Guard on the thing you are about to touch, not on a global that a shim * also provides. See `.agents/rules/adapters-ssr.md`. */ function themeRoot(): HTMLElement | undefined { if (typeof document === 'undefined') return undefined; return document.documentElement ?? undefined; } /** * * Top navigation bar with site title, nav links, and dark/light theme toggle. */ export class StarlightHeader extends FASTElement { siteTitle = ''; nav: NavItem[] = []; currentPath = ''; navOpen = false; hasSidebar = false; _theme = 'light'; /** * Keep the toggle's icon on the theme the page is actually showing. * * THIS READS, IT DOES NOT DECIDE. The head script in route-meta.ts sets * data-theme before the first paint, from the reader's stored choice or, * when they have made none, from the system. This used to resolve it a * second time and fall back to 'light' with no look at * prefers-color-scheme, so on a dark system every page carrying the header * flipped to light right after it loaded. */ private _readTheme = (): void => { if (!themeRoot()) return; this._theme = document.documentElement.getAttribute('data-theme') === 'dark' ? 'dark' : 'light'; }; private _systemTheme?: MediaQueryList; override connectedCallback(): void { super.connectedCallback(); // One guard for the whole block: with no documentElement there is no // theme to read and no system preference worth listening to, and FAST // runs this method during SSR. if (!themeRoot()) return; this._readTheme(); // The head script follows the system while the reader has stored no // choice, so the icon has to follow it too. The head script's own // listener was registered first, in , so by the time this one runs // data-theme is already up to date. if (typeof window !== 'undefined' && typeof window.matchMedia === 'function') { this._systemTheme = window.matchMedia('(prefers-color-scheme: dark)'); this._systemTheme.addEventListener('change', this._readTheme); } } override disconnectedCallback(): void { super.disconnectedCallback(); this._systemTheme?.removeEventListener('change', this._readTheme); } toggleTheme() { const next = this._theme === 'light' ? 'dark' : 'light'; this._theme = next; // Writing the choice is what stops the head script's system listener // from overriding it later. if (typeof localStorage !== 'undefined') { try { localStorage.setItem('sl-theme', next); } catch { // Site data blocked. The choice holds for this page either way. } } if (themeRoot()) { document.documentElement.setAttribute('data-theme', next); } } toggleNav() { this.dispatchEvent( new CustomEvent('sl-nav-toggle', { bubbles: true, composed: true }), ); } } Observable.defineProperty(StarlightHeader.prototype, 'siteTitle'); Observable.defineProperty(StarlightHeader.prototype, 'nav'); Observable.defineProperty(StarlightHeader.prototype, 'currentPath'); Observable.defineProperty(StarlightHeader.prototype, 'navOpen'); Observable.defineProperty(StarlightHeader.prototype, 'hasSidebar'); Observable.defineProperty(StarlightHeader.prototype, '_theme'); const template = html`
${when(x => x.hasSidebar, html` `)} ${x => x.siteTitle}
`; const styles = [pageReset, css` :host { display: block; position: sticky; top: 0; z-index: 100; } header { height: var(--sl-nav-height, 3.5rem); background-color: var(--sl-color-bg-nav, #fff); border-bottom: 1px solid var(--sl-color-border, #e8e8e8); display: flex; align-items: center; padding: 0 var(--sl-content-pad-x, 1.5rem); gap: 1rem; } .menu-btn { display: none; appearance: none; background: none; border: 1px solid var(--sl-color-border, #e8e8e8); border-radius: var(--sl-border-radius, 0.375rem); width: 2.25rem; height: 2.25rem; align-items: center; justify-content: center; cursor: pointer; color: var(--sl-color-text, #23262f); transition: background-color 0.15s; flex-shrink: 0; padding: 0; } .menu-btn:hover { background-color: var(--sl-color-gray-2, #e8e8e8); } .menu-btn svg { width: 1.1rem; height: 1.1rem; } @media (max-width: 72rem) { .menu-btn { display: flex; } } /* THE BRAND FACE. --sl-font-brand is what the wordmark and the navigation are set in, and it falls back to the body sans, so a site that never sets it looks exactly as it did. A site that wants the terminal character in its header sets it once, to the mono, and both the name and the links follow. It is a token rather than a fork of this component because that is the whole of the difference: two declarations, not a second header. */ .site-title { font-family: var(--sl-font-brand, var(--sl-font-sans)); font-size: var(--sl-text-lg, 1.125rem); font-weight: 700; color: var(--sl-color-text, #23262f); text-decoration: none; white-space: nowrap; /* A flex item will not shrink below its own text, so a long site name pushes the theme toggle past the right edge of a 320px screen. These three let the row give way and end the name in an ellipsis instead. */ min-width: 0; overflow: hidden; text-overflow: ellipsis; } .site-title:hover { opacity: 0.85; } nav { display: flex; align-items: center; gap: 0.25rem; flex: 1; /* min-width: 0, or a flex item refuses to shrink below its content and the whole header grows past a phone's screen. On the docs pages the nav is hidden behind the hamburger below 72rem and this never showed; the landing page has no sidebar, so it keeps its links and needs the row to be able to give way. */ min-width: 0; } /* A phone cannot fit four links, a search control and two icon buttons. The links SCROLL rather than disappear: dropping one would take a destination away from exactly the reader with the least room to go looking for it. The bar is hidden because a scrollbar inside a header is noise, and the links are still reachable by keyboard and by swipe. */ @media (max-width: 48rem) { nav { overflow-x: auto; scrollbar-width: none; -ms-overflow-style: none; } nav::-webkit-scrollbar { display: none; } nav a { flex-shrink: 0; } } nav a { font-family: var(--sl-font-brand, var(--sl-font-sans)); padding: 0.35rem 0.75rem; font-size: var(--sl-text-sm, 0.875rem); font-weight: 500; color: var(--sl-color-gray-5, #4b4b4b); text-decoration: none; border-radius: var(--sl-border-radius, 0.375rem); transition: color 0.15s, background-color 0.15s; } nav a:hover { color: var(--sl-color-text, #23262f); background-color: var(--sl-color-gray-2, #e8e8e8); } nav a[aria-current='page'] { color: var(--sl-color-accent, #7c3aed); background-color: var(--sl-color-accent-low, #ede9fe); } .theme-toggle { margin-left: auto; appearance: none; background: none; border: 1px solid var(--sl-color-border, #e8e8e8); border-radius: var(--sl-border-radius, 0.375rem); width: 2.25rem; height: 2.25rem; display: flex; align-items: center; justify-content: center; cursor: pointer; font-size: 1rem; color: var(--sl-color-text, #23262f); transition: background-color 0.15s; flex-shrink: 0; } .theme-toggle:hover { background-color: var(--sl-color-gray-2, #e8e8e8); } `]; StarlightHeader.define({ name: 'starlight-header', template, styles }); export default StarlightHeader;