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;