starlight-theme-bejamas 0.1.18 → 0.2.3

package/src/lib/theme-choice.ts

@@ -0,0 +1,346 @@
+export const STARLIGHT_THEME_STORAGE_KEY = "starlight-theme";
+export const THEME_TOGGLE_CHANGED_EVENT = "theme-toggle-changed";
+
+export type ThemeChoice = "auto" | "dark" | "light";
+export type ThemeMode = "dark" | "light";
+
+export interface ThemeRoot {
+  dataset: Record<string, string | undefined>;
+  classList: {
+    add: (...tokens: string[]) => void;
+    remove: (...tokens: string[]) => void;
+  };
+}
+
+type ThemeClassList = ThemeRoot["classList"] & {
+  contains?: (token: string) => boolean;
+};
+
+type ThemeRootElement = ThemeRoot & {
+  classList: ThemeClassList;
+};
+
+type ThemeStorageReader = Pick<Storage, "getItem"> | null | undefined;
+type ThemeStorageWriter = Pick<Storage, "setItem"> | null | undefined;
+
+const THEME_CHOICE_TAB_SELECTOR = '[data-slot="tabs"][data-theme-choice-tabs]';
+
+function getElementsWithSelf<T extends Element>(
+  root: ParentNode,
+  selector: string,
+): T[] {
+  const matches: T[] = [];
+
+  if (
+    typeof Element !== "undefined" &&
+    root instanceof Element &&
+    root.matches(selector)
+  ) {
+    matches.push(root as T);
+  }
+
+  matches.push(...Array.from(root.querySelectorAll<T>(selector)));
+
+  return matches;
+}
+
+export function parseStoredThemeChoice(value: unknown): ThemeChoice {
+  return value === "auto" || value === "dark" || value === "light"
+    ? value
+    : "auto";
+}
+
+export function loadStoredThemeChoice(storage: ThemeStorageReader): ThemeChoice {
+  try {
+    return parseStoredThemeChoice(
+      storage?.getItem(STARLIGHT_THEME_STORAGE_KEY),
+    );
+  } catch {
+    return "auto";
+  }
+}
+
+export function resolveThemeMode(
+  themeChoice: ThemeChoice,
+  prefersLight: boolean,
+): ThemeMode {
+  if (themeChoice === "light" || themeChoice === "dark") {
+    return themeChoice;
+  }
+
+  return prefersLight ? "light" : "dark";
+}
+
+export function applyThemeModeToRoot(
+  root: ThemeRoot,
+  themeChoice: ThemeChoice,
+  themeMode: ThemeMode,
+): void {
+  root.dataset.theme = themeMode;
+  root.dataset.themeChoice = themeChoice;
+  root.classList.remove("light", "dark");
+  root.classList.add(themeMode);
+}
+
+export function storeThemeChoice(
+  storage: ThemeStorageWriter,
+  themeChoice: ThemeChoice,
+): void {
+  try {
+    storage?.setItem(
+      STARLIGHT_THEME_STORAGE_KEY,
+      themeChoice === "light" || themeChoice === "dark" ? themeChoice : "",
+    );
+  } catch {}
+}
+
+export function getThemeChoiceFromRoot(
+  root: Pick<ThemeRoot, "dataset">,
+): ThemeChoice {
+  return parseStoredThemeChoice(root.dataset.themeChoice);
+}
+
+export function getThemeModeFromRoot(
+  root: ThemeRootElement,
+  fallbackMode: ThemeMode,
+): ThemeMode {
+  if (root.dataset.theme === "light" || root.dataset.theme === "dark") {
+    return root.dataset.theme;
+  }
+
+  if (root.classList.contains?.("dark")) {
+    return "dark";
+  }
+
+  if (root.classList.contains?.("light")) {
+    return "light";
+  }
+
+  return fallbackMode;
+}
+
+function syncThemeChoiceTabControls(
+  themeChoice: ThemeChoice,
+  root: ParentNode,
+): void {
+  const tabsRoots = new Set<HTMLElement>();
+
+  for (const tabsRoot of getElementsWithSelf<HTMLElement>(
+    root,
+    THEME_CHOICE_TAB_SELECTOR,
+  )) {
+    tabsRoots.add(tabsRoot);
+  }
+
+  for (const picker of getElementsWithSelf<HTMLElement>(
+    root,
+    "starlight-theme-select",
+  )) {
+    const tabsRoot = picker.querySelector<HTMLElement>(THEME_CHOICE_TAB_SELECTOR);
+    if (tabsRoot) {
+      tabsRoots.add(tabsRoot);
+    }
+  }
+
+  for (const tabsRoot of tabsRoots) {
+    tabsRoot.dataset.defaultValue = themeChoice;
+    tabsRoot.dataset.value = themeChoice;
+    tabsRoot.dispatchEvent(
+      new CustomEvent("tabs:set", { detail: { value: themeChoice } }),
+    );
+  }
+}
+
+function syncLegacyThemeChoiceSelectControls(
+  themeChoice: ThemeChoice,
+  root: ParentNode,
+): void {
+  for (const picker of getElementsWithSelf<HTMLElement>(
+    root,
+    "starlight-theme-select",
+  )) {
+    const nativeSelect = picker.querySelector<HTMLSelectElement>("select");
+    if (nativeSelect) {
+      nativeSelect.value = themeChoice;
+    }
+
+    const selectRoot = picker.querySelector<HTMLElement>(
+      '#starlight-theme-select, [data-slot="select"]',
+    );
+    if (!selectRoot) {
+      continue;
+    }
+
+    selectRoot.dataset.defaultValue = themeChoice;
+    selectRoot.dataset.value = themeChoice;
+    selectRoot.dispatchEvent(
+      new CustomEvent("select:set", { detail: { value: themeChoice } }),
+    );
+  }
+}
+
+export function syncThemeChoiceControls(
+  themeChoice: ThemeChoice,
+  root: ParentNode = document,
+): void {
+  syncThemeChoiceTabControls(themeChoice, root);
+  syncLegacyThemeChoiceSelectControls(themeChoice, root);
+}
+
+export function dispatchThemeToggleChange(
+  target: EventTarget,
+  themeMode: ThemeMode,
+  themeChoice: ThemeChoice,
+): void {
+  target.dispatchEvent(
+    new CustomEvent(THEME_TOGGLE_CHANGED_EVENT, {
+      detail: {
+        theme: themeMode,
+        themeChoice,
+      },
+    }),
+  );
+}
+
+export function setThemeChoice(
+  themeChoice: ThemeChoice,
+  options: {
+    storage?: ThemeStorageWriter;
+    root?: ThemeRootElement;
+    prefersLight?: boolean;
+    controlsRoot?: ParentNode;
+    dispatchTarget?: EventTarget;
+    emitEvent?: boolean;
+  } = {},
+): ThemeMode {
+  const root = options.root ?? (document.documentElement as HTMLElement);
+  const effectiveTheme = resolveThemeMode(
+    themeChoice,
+    options.prefersLight ??
+      window.matchMedia("(prefers-color-scheme: light)").matches,
+  );
+
+  applyThemeModeToRoot(root, themeChoice, effectiveTheme);
+  storeThemeChoice(options.storage ?? localStorage, themeChoice);
+  syncThemeChoiceControls(themeChoice, options.controlsRoot ?? document);
+
+  if (options.emitEvent !== false) {
+    dispatchThemeToggleChange(
+      options.dispatchTarget ?? window,
+      effectiveTheme,
+      themeChoice,
+    );
+  }
+
+  return effectiveTheme;
+}
+
+export function buildThemeChoiceBootstrapInlineScript(): string {
+  return `(function () {
+  const storageKey = ${JSON.stringify(STARLIGHT_THEME_STORAGE_KEY)};
+  const eventName = ${JSON.stringify(THEME_TOGGLE_CHANGED_EVENT)};
+  const parseStoredThemeChoice = (value) =>
+    value === "auto" || value === "dark" || value === "light" ? value : "auto";
+  const loadStoredThemeChoice = () => {
+    try {
+      return parseStoredThemeChoice(
+        typeof localStorage !== "undefined" ? localStorage.getItem(storageKey) : null,
+      );
+    } catch {
+      return "auto";
+    }
+  };
+  const resolveThemeMode = (themeChoice, prefersLight) => {
+    if (themeChoice === "light" || themeChoice === "dark") {
+      return themeChoice;
+    }
+
+    return prefersLight ? "light" : "dark";
+  };
+  const applyThemeModeToRoot = (themeChoice) => {
+    const themeMode = resolveThemeMode(
+      themeChoice,
+      matchMedia("(prefers-color-scheme: light)").matches,
+    );
+    const root = document.documentElement;
+
+    root.dataset.theme = themeMode;
+    root.dataset.themeChoice = themeChoice;
+    root.classList.remove("light", "dark");
+    root.classList.add(themeMode);
+
+    return themeMode;
+  };
+  const syncThemeChoiceControls = (themeChoice) => {
+    document
+      .querySelectorAll('[data-slot="tabs"][data-theme-choice-tabs]')
+      .forEach((tabsRoot) => {
+        tabsRoot.dataset.defaultValue = themeChoice;
+        tabsRoot.dataset.value = themeChoice;
+        tabsRoot.dispatchEvent(
+          new CustomEvent("tabs:set", { detail: { value: themeChoice } }),
+        );
+      });
+
+    document.querySelectorAll("starlight-theme-select").forEach((picker) => {
+      const nativeSelect = picker.querySelector("select");
+      if (nativeSelect instanceof HTMLSelectElement) {
+        nativeSelect.value = themeChoice;
+      }
+
+      const selectRoot = picker.querySelector(
+        '#starlight-theme-select, [data-slot="select"]',
+      );
+      if (!(selectRoot instanceof HTMLElement)) {
+        return;
+      }
+
+      selectRoot.dataset.defaultValue = themeChoice;
+      selectRoot.dataset.value = themeChoice;
+      selectRoot.dispatchEvent(
+        new CustomEvent("select:set", { detail: { value: themeChoice } }),
+      );
+    });
+  };
+  const dispatchThemeToggleChange = (themeMode, themeChoice) => {
+    window.dispatchEvent(
+      new CustomEvent(eventName, {
+        detail: {
+          theme: themeMode,
+          themeChoice,
+        },
+      }),
+    );
+  };
+  const syncThemeChoice = (themeChoice, emitEvent) => {
+    const themeMode = applyThemeModeToRoot(themeChoice);
+    syncThemeChoiceControls(themeChoice);
+    if (emitEvent) {
+      dispatchThemeToggleChange(themeMode, themeChoice);
+    }
+  };
+  const syncStoredThemeChoice = (emitEvent) => {
+    syncThemeChoice(loadStoredThemeChoice(), emitEvent);
+  };
+  const mediaQuery = matchMedia("(prefers-color-scheme: light)");
+  const onMediaChange = () => {
+    if (loadStoredThemeChoice() === "auto") {
+      syncThemeChoice("auto", true);
+    }
+  };
+
+  syncStoredThemeChoice(false);
+
+  window.addEventListener("storage", (event) => {
+    if (event.key === storageKey) {
+      syncStoredThemeChoice(true);
+    }
+  });
+
+  if (typeof mediaQuery.addEventListener === "function") {
+    mediaQuery.addEventListener("change", onMediaChange);
+  } else if (typeof mediaQuery.addListener === "function") {
+    mediaQuery.addListener(onMediaChange);
+  }
+})();`;
+}

package/src/lib/theme-stylesheet-runtime.test.ts

@@ -0,0 +1,246 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { refreshCurrentThemeStylesheet } from "./theme-stylesheet";
+
+const ACTIVE_SELECTOR = "link[data-current-theme-stylesheet]";
+const PENDING_SELECTOR = "link[data-pending-current-theme-stylesheet]";
+
+type Listener = (event: Event) => void;
+
+class FakeLinkElement {
+  href = "";
+  rel = "stylesheet";
+  private attributes = new Map<string, string>();
+  private listeners = new Map<string, Set<Listener>>();
+
+  constructor(
+    private readonly document: FakeDocument,
+    href = "",
+  ) {
+    this.href = href;
+  }
+
+  cloneNode() {
+    const clone = new FakeLinkElement(this.document, this.href);
+    clone.rel = this.rel;
+
+    for (const [name, value] of this.attributes) {
+      clone.attributes.set(name, value);
+    }
+
+    return clone;
+  }
+
+  setAttribute(name: string, value: string) {
+    this.attributes.set(name, value);
+  }
+
+  removeAttribute(name: string) {
+    this.attributes.delete(name);
+  }
+
+  hasAttribute(name: string) {
+    return this.attributes.has(name);
+  }
+
+  addEventListener(type: string, listener: Listener) {
+    const listeners = this.listeners.get(type) ?? new Set<Listener>();
+    listeners.add(listener);
+    this.listeners.set(type, listeners);
+  }
+
+  removeEventListener(type: string, listener: Listener) {
+    this.listeners.get(type)?.delete(listener);
+  }
+
+  dispatchEvent(event: Event) {
+    this.listeners.get(event.type)?.forEach((listener) => listener(event));
+    return true;
+  }
+
+  insertAdjacentElement(position: InsertPosition, element: FakeLinkElement) {
+    if (position !== "afterend") {
+      throw new Error(`Unsupported insert position: ${position}`);
+    }
+
+    this.document.insertAfter(this, element);
+    return element;
+  }
+
+  remove() {
+    this.document.remove(this);
+  }
+}
+
+class FakeDocument {
+  links: FakeLinkElement[] = [];
+
+  querySelector<T extends FakeLinkElement>(selector: string) {
+    return (this.querySelectorAll(selector)[0] ?? null) as T | null;
+  }
+
+  querySelectorAll<T extends FakeLinkElement>(selector: string) {
+    if (selector === ACTIVE_SELECTOR) {
+      return this.links.filter((link) =>
+        link.hasAttribute("data-current-theme-stylesheet"),
+      ) as T[];
+    }
+
+    if (selector === PENDING_SELECTOR) {
+      return this.links.filter((link) =>
+        link.hasAttribute("data-pending-current-theme-stylesheet"),
+      ) as T[];
+    }
+
+    if (selector === "link") {
+      return [...this.links] as T[];
+    }
+
+    return [] as T[];
+  }
+
+  append(link: FakeLinkElement) {
+    this.links.push(link);
+  }
+
+  insertAfter(target: FakeLinkElement, link: FakeLinkElement) {
+    const index = this.links.indexOf(target);
+    if (index === -1) {
+      this.links.push(link);
+      return;
+    }
+
+    this.links.splice(index + 1, 0, link);
+  }
+
+  remove(link: FakeLinkElement) {
+    this.links = this.links.filter((entry) => entry !== link);
+  }
+}
+
+const originalDocument = globalThis.document;
+const originalWindow = globalThis.window;
+
+function createEnvironment() {
+  const document = new FakeDocument();
+  const window = {
+    location: { origin: "https://ui.bejamas.com" },
+    requestAnimationFrame: (callback: FrameRequestCallback) => {
+      callback(0);
+      return 1;
+    },
+    setTimeout,
+  } as unknown as Window & typeof globalThis;
+
+  globalThis.document = document as unknown as Document;
+  globalThis.window = window;
+
+  return { document };
+}
+
+function appendActiveStylesheet(document: FakeDocument, href?: string) {
+  const stylesheet = new FakeLinkElement(
+    document,
+    href ?? "https://ui.bejamas.com/r/themes/current-theme.css",
+  );
+  stylesheet.setAttribute("data-current-theme-stylesheet", "");
+  document.append(stylesheet);
+  return stylesheet;
+}
+
+describe("refreshCurrentThemeStylesheet", () => {
+  beforeEach(() => {
+    createEnvironment();
+  });
+
+  afterEach(() => {
+    globalThis.document = originalDocument;
+    globalThis.window = originalWindow;
+  });
+
+  test("keeps the current stylesheet active until the replacement loads", async () => {
+    const document = globalThis.document as unknown as FakeDocument;
+    const currentStylesheet = appendActiveStylesheet(document);
+
+    const refreshPromise = refreshCurrentThemeStylesheet();
+    const pendingStylesheet =
+      document.querySelector<FakeLinkElement>(PENDING_SELECTOR);
+
+    expect(refreshPromise).toBeInstanceOf(Promise);
+    expect(document.querySelectorAll("link")).toHaveLength(2);
+    expect(document.querySelector(ACTIVE_SELECTOR)).toBe(currentStylesheet);
+    expect(pendingStylesheet).not.toBeNull();
+    expect(pendingStylesheet?.href).not.toBe(currentStylesheet.href);
+
+    pendingStylesheet?.dispatchEvent(new Event("load"));
+    await refreshPromise;
+
+    const activeStylesheet =
+      document.querySelector<FakeLinkElement>(ACTIVE_SELECTOR);
+    expect(document.querySelectorAll("link")).toHaveLength(1);
+    expect(document.querySelector(PENDING_SELECTOR)).toBeNull();
+    expect(activeStylesheet).toBe(pendingStylesheet);
+    expect(activeStylesheet?.href).toContain("/r/themes/current-theme.css?v=");
+  });
+
+  test("keeps the current stylesheet when the replacement fails to load", async () => {
+    const document = globalThis.document as unknown as FakeDocument;
+    const currentStylesheet = appendActiveStylesheet(document);
+
+    const refreshPromise = refreshCurrentThemeStylesheet();
+    const pendingStylesheet =
+      document.querySelector<FakeLinkElement>(PENDING_SELECTOR);
+
+    pendingStylesheet?.dispatchEvent(new Event("error"));
+    await refreshPromise;
+
+    expect(document.querySelectorAll("link")).toHaveLength(1);
+    expect(document.querySelector(ACTIVE_SELECTOR)).toBe(currentStylesheet);
+    expect(document.querySelector(PENDING_SELECTOR)).toBeNull();
+  });
+
+  test("uses a unique cache-busting version for each refresh", async () => {
+    const document = globalThis.document as unknown as FakeDocument;
+    appendActiveStylesheet(document);
+
+    const firstRefresh = refreshCurrentThemeStylesheet();
+    const firstHref =
+      document.querySelector<FakeLinkElement>(PENDING_SELECTOR)?.href;
+
+    // A second refresh in the same tick (same Date.now()) must still produce a
+    // distinct URL, otherwise the browser can reuse a stale cached response.
+    const secondRefresh = refreshCurrentThemeStylesheet();
+    const secondPending =
+      document.querySelector<FakeLinkElement>(PENDING_SELECTOR);
+
+    expect(secondPending?.href).toContain("/r/themes/current-theme.css?v=");
+    expect(secondPending?.href).not.toBe(firstHref);
+
+    secondPending?.dispatchEvent(new Event("load"));
+    await Promise.all([firstRefresh, secondRefresh]);
+  });
+
+  test("cancels an older pending swap when a newer one starts", async () => {
+    const document = globalThis.document as unknown as FakeDocument;
+    appendActiveStylesheet(document);
+
+    const firstRefresh = refreshCurrentThemeStylesheet();
+    const firstPendingStylesheet =
+      document.querySelector<FakeLinkElement>(PENDING_SELECTOR);
+
+    const secondRefresh = refreshCurrentThemeStylesheet();
+    const secondPendingStylesheet =
+      document.querySelector<FakeLinkElement>(PENDING_SELECTOR);
+
+    expect(secondPendingStylesheet).not.toBe(firstPendingStylesheet);
+    expect(document.querySelectorAll(PENDING_SELECTOR)).toHaveLength(1);
+
+    secondPendingStylesheet?.dispatchEvent(new Event("load"));
+    await Promise.all([firstRefresh, secondRefresh]);
+
+    expect(document.querySelectorAll("link")).toHaveLength(1);
+    expect(document.querySelector(ACTIVE_SELECTOR)).toBe(
+      secondPendingStylesheet,
+    );
+    expect(document.querySelector(PENDING_SELECTOR)).toBeNull();
+  });
+});

package/src/lib/theme-stylesheet.test.ts

@@ -0,0 +1,16 @@
+import { describe, expect, test } from "bun:test";
+import { buildCurrentThemeStylesheetHref } from "./theme-stylesheet";
+
+describe("current theme stylesheet helpers", () => {
+  test("adds a cache-busting query param to relative hrefs", () => {
+    expect(
+      buildCurrentThemeStylesheetHref("/r/themes/current-theme.css", 123),
+    ).toBe("/r/themes/current-theme.css?v=123");
+  });
+
+  test("preserves existing query params when cache-busting", () => {
+    expect(
+      buildCurrentThemeStylesheetHref("/r/themes/current-theme.css?foo=bar", 123),
+    ).toBe("/r/themes/current-theme.css?foo=bar&v=123");
+  });
+});