import { LitElement, html, css } from "lit"; import { customElement } from "lit/decorators.js"; import { pageReset } from '@beatzball/litro/runtime/page-reset.js'; export interface NavItem { label: string; href: string; } /** * A real browser, not a server DOM shim. * * `typeof document !== "undefined"` is NOT enough. A server-side DOM shim can * define `document` and still leave `documentElement` undefined, which is how * the FAST copy of this header threw * "Cannot read properties of undefined (reading 'getAttribute')" during SSR * and took down every page that carried it. Lit's SSR never calls * firstUpdated(), so this copy never reached the bug — but the adapter copies * are read against each other, and the shape has to be the same in all of * them. See `.agents/rules/adapters-ssr.md`. * * Guard on the thing you are about to touch, not on a global a shim provides. */ 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. */ @customElement("starlight-header") export class StarlightHeader extends LitElement { static override properties = { siteTitle: { type: String }, nav: { type: Array }, currentPath: { type: String }, navOpen: { type: Boolean }, hasSidebar: { type: Boolean }, _theme: { type: String, state: true }, }; static override 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); } `, ]; 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. Resolving it a second time * here would answer a moment later, and a different answer would overwrite * a correct value with a wrong one — which is what this component used to * do: it fell back to "light" with no look at prefers-color-scheme, so on * a dark system every page carrying this header flipped to light right * after it loaded. */ private _readTheme = () => { if (!themeRoot()) return; this._theme = document.documentElement.getAttribute("data-theme") === "dark" ? "dark" : "light"; }; private _systemTheme?: MediaQueryList; override firstUpdated() { // One guard for the whole block: with no documentElement there is no // theme to read and no system preference worth listening to. 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() { super.disconnectedCallback(); this._systemTheme?.removeEventListener("change", this._readTheme); } private _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); } } private _toggleNav() { this.dispatchEvent( new CustomEvent("sl-nav-toggle", { bubbles: true, composed: true }), ); } override render() { const icon = this._theme === "dark" ? "☀️" : "🌙"; const label = this._theme === "dark" ? "Switch to light mode" : "Switch to dark mode"; return html`
${this.hasSidebar ? html` ` : ""} ${this.siteTitle}
`; } } export default StarlightHeader;