import { Elena, html, unsafeHTML } from '@elenajs/core';
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. Elena's SSR runs only
* willUpdate() and render() (see `.agents/rules/adapters-ssr.md`, SSR-002),
* so this copy never reached the bug — but the three adapter copies are read
* against each other, and the shape has to be the same in all of them.
*
* 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.
* Light DOM — styles scoped via @scope.
*
*/
export class StarlightHeader extends Elena(HTMLElement) {
static tagName = 'starlight-header';
static props = ['sitetitle', 'nav', 'currentpath', 'navopen', 'hassidebar', '_theme'];
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();
// With no documentElement there is no theme to read and no system
// preference worth listening to. A server DOM shim reaches here.
if (themeRoot()) {
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);
}
}
// Elena renders plain HTML — wire up click events via delegation
this.addEventListener('click', this._handleClick);
}
override disconnectedCallback(): void {
super.disconnectedCallback();
this._systemTheme?.removeEventListener('change', this._readTheme);
this.removeEventListener('click', this._handleClick);
}
private _handleClick = (e: Event) => {
const btn = (e.target as HTMLElement).closest('[data-action]') as HTMLElement | null;
if (!btn) return;
const action = btn.getAttribute('data-action');
if (action === 'toggle-theme') this.toggleTheme();
else if (action === 'toggle-nav') this.toggleNav();
};
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 }),
);
}
render() {
const menuBtnClass = this.hassidebar
? `menu-btn${this.navopen ? ' nav-open' : ''}`
: 'menu-btn menu-btn-hidden';
const navLinks = (this.nav || []).map(item => {
const current = this.currentpath.startsWith(item.href) ? 'page' : 'false';
return `${item.label}`;
}).join('');
const themeLabel = this._theme === 'dark' ? 'Switch to light mode' : 'Switch to dark mode';
const themeIcon = this._theme === 'dark' ? '\u2600\uFE0F' : '\uD83C\uDF19';
return html`
`;
}
}
StarlightHeader.define();
export default StarlightHeader;