starlight-theme-bejamas 0.1.18 → 0.2.3

package/src/lib/theme-stylesheet.ts

@@ -0,0 +1,123 @@
+export const CURRENT_THEME_STYLESHEET_SELECTOR =
+  "link[data-current-theme-stylesheet]";
+
+export function buildCurrentThemeStylesheetHref(
+  href: string,
+  version: string | number,
+) {
+  const url = new URL(href, "https://ui.bejamas.com");
+  url.searchParams.set("v", String(version));
+
+  const isAbsolute = /^[a-zA-Z][a-zA-Z\d+\-.]*:/.test(href);
+  return isAbsolute
+    ? url.toString()
+    : `${url.pathname}${url.search}${url.hash}`;
+}
+
+const PENDING_THEME_STYLESHEET_SELECTOR =
+  "link[data-pending-current-theme-stylesheet]";
+
+let stylesheetSwapToken = 0;
+let stylesheetVersionCounter = 0;
+let cancelPendingThemeStylesheetSwap: (() => void) | null = null;
+
+function getAnimationFrame() {
+  if (typeof window !== "undefined" && window.requestAnimationFrame) {
+    return window.requestAnimationFrame.bind(window);
+  }
+
+  return (callback: FrameRequestCallback) =>
+    window.setTimeout(() => callback(performance.now()), 0);
+}
+
+export function refreshCurrentThemeStylesheet() {
+  const currentStylesheet = document.querySelector<HTMLLinkElement>(
+    "link[data-current-theme-stylesheet]",
+  );
+
+  if (!currentStylesheet) {
+    return Promise.resolve();
+  }
+
+  cancelPendingThemeStylesheetSwap?.();
+
+  // Strictly-monotonic version so two refreshes in the same millisecond can
+  // never collide on a cached response (which would swap in a stale theme).
+  const nextHref = buildCurrentThemeStylesheetHref(
+    currentStylesheet.href,
+    `${Date.now()}-${++stylesheetVersionCounter}`,
+  );
+  const nextStylesheet = currentStylesheet.cloneNode(true) as HTMLLinkElement;
+  const swapToken = ++stylesheetSwapToken;
+  const requestAnimationFrame = getAnimationFrame();
+
+  nextStylesheet.href = nextHref;
+  nextStylesheet.removeAttribute("data-current-theme-stylesheet");
+  nextStylesheet.setAttribute("data-pending-current-theme-stylesheet", "");
+
+  document
+    .querySelectorAll<HTMLLinkElement>(PENDING_THEME_STYLESHEET_SELECTOR)
+    .forEach((link) => {
+      if (link !== nextStylesheet) {
+        link.remove();
+      }
+    });
+
+  return new Promise<void>((resolve) => {
+    let settled = false;
+
+    const settle = () => {
+      if (settled) {
+        return;
+      }
+
+      settled = true;
+      if (cancelPendingThemeStylesheetSwap === cancel) {
+        cancelPendingThemeStylesheetSwap = null;
+      }
+      resolve();
+    };
+
+    const cleanup = () => {
+      nextStylesheet.removeEventListener("load", onLoad);
+      nextStylesheet.removeEventListener("error", onError);
+    };
+
+    const cancel = () => {
+      cleanup();
+      nextStylesheet.remove();
+      settle();
+    };
+
+    const onError = () => {
+      cancel();
+    };
+
+    const onLoad = () => {
+      cleanup();
+
+      if (swapToken !== stylesheetSwapToken) {
+        nextStylesheet.remove();
+        settle();
+        return;
+      }
+
+      currentStylesheet.removeAttribute("data-current-theme-stylesheet");
+      nextStylesheet.removeAttribute("data-pending-current-theme-stylesheet");
+      nextStylesheet.setAttribute("data-current-theme-stylesheet", "");
+
+      requestAnimationFrame(() => {
+        if (swapToken === stylesheetSwapToken) {
+          currentStylesheet.remove();
+        }
+
+        settle();
+      });
+    };
+
+    cancelPendingThemeStylesheetSwap = cancel;
+    nextStylesheet.addEventListener("load", onLoad, { once: true });
+    nextStylesheet.addEventListener("error", onError, { once: true });
+    currentStylesheet.insertAdjacentElement("afterend", nextStylesheet);
+  });
+}

package/src/overrides/MobileTableOfContents.astro

@@ -87,12 +87,12 @@ const { toc } = Astro.locals.starlightRoute;
       align-items: center;
       justify-content: space-between;
       border: 1px solid var(--sl-color-gray-5);
-      border-radius: 0.5rem;
+      border-radius: calc(var(--radius) - 2px);
       padding-block: 0.5rem;
       padding-inline-start: 0.75rem;
       padding-inline-end: 0.5rem;
       line-height: 1;
-      background-color: var(--sl-color-black);
+      background-color: var(--background);
       user-select: none;
       cursor: pointer;
       font-weight: 500;
@@ -133,11 +133,11 @@ const { toc } = Astro.locals.starlightRoute;
       transition: background 200ms ease-out;
     }
     details[open] .toggle {
-      color: var(--sl-color-white);
+      color: var(--foreground);
       border-color: var(--sl-color-accent);
     }
     details .toggle:hover {
-      color: var(--sl-color-white);
+      color: var(--foreground);
       border-color: var(--sl-color-gray-2);
     }
 
@@ -152,7 +152,7 @@ const { toc } = Astro.locals.starlightRoute;
       white-space: nowrap;
       text-overflow: ellipsis;
       overflow: hidden;
-      color: var(--sl-color-white);
+      color: var(--foreground);
     }
 
     .dropdown {
@@ -164,7 +164,7 @@ const { toc } = Astro.locals.starlightRoute;
         85vh - var(--sl-nav-height) - var(--sl-mobile-toc-height)
       );
       overflow-y: auto;
-      background-color: var(--sl-color-black);
+      background-color: var(--popover);
       box-shadow: var(--sl-shadow-md);
       overscroll-behavior: contain;
     }

package/src/overrides/PageFrame.astro

@@ -28,83 +28,44 @@ const isSplashTemplate = template === "splash";
         aria-label={Astro.locals.t("sidebarNav.accessibleLabel")}
       >
         <MobileMenuToggle />
-        <div id="starlight__sidebar" class="sidebar-pane">
+        <script>
+          if (!customElements.get("sl-sidebar-pane")) {
+            class StarlightSidebarPane extends HTMLElement {
+              constructor() {
+                super();
+
+                const desktopMediaQuery = matchMedia("(min-width: 64rem)");
+                const updatePopover = () => {
+                  this.popover = desktopMediaQuery.matches ? null : "auto";
+                };
+                updatePopover();
+                desktopMediaQuery.addEventListener("change", updatePopover);
+
+                this.addEventListener("toggle", () => {
+                  const isOpen = this.matches(":popover-open");
+                  document
+                    .querySelectorAll<HTMLElement>(".main-frame, .sl-skip-link")
+                    .forEach((element) => element.toggleAttribute("inert", isOpen));
+
+                  if (isOpen && this.closest(".sidebar-splash")) {
+                    this.scrollTop = 0;
+                  }
+                });
+              }
+            }
+
+            customElements.define("sl-sidebar-pane", StarlightSidebarPane);
+          }
+        </script>
+        <sl-sidebar-pane popover="" id="starlight__sidebar" class="sidebar-pane">
           <div class="sidebar-content sl-flex">
             <slot name="sidebar" />
           </div>
-        </div>
+        </sl-sidebar-pane>
       </nav>
     )
   }
 
-  {
-    isSplashTemplate && (
-      <script is:inline>
-        (() => {
-          const installReset = () => {
-            const nav = document.querySelector("nav.sidebar-splash");
-            if (!(nav instanceof HTMLElement)) return () => {};
-
-            const pane = nav.querySelector("#starlight__sidebar");
-            const toggle = nav.querySelector("starlight-menu-button");
-
-            if (!(pane instanceof HTMLElement)) return () => {};
-
-            const resetToTop = () => {
-              pane.scrollTop = 0;
-            };
-
-            // Avoid opening splash menus at a persisted offset.
-            resetToTop();
-
-            if (!(toggle instanceof HTMLElement)) return () => {};
-
-            const onToggleChange = () => {
-              if (toggle.getAttribute("aria-expanded") === "true") {
-                requestAnimationFrame(resetToTop);
-              }
-            };
-
-            const onToggleClick = () => {
-              requestAnimationFrame(onToggleChange);
-            };
-
-            toggle.addEventListener("click", onToggleClick);
-
-            const observer = new MutationObserver(onToggleChange);
-            observer.observe(toggle, {
-              attributes: true,
-              attributeFilter: ["aria-expanded"],
-            });
-
-            return () => {
-              toggle.removeEventListener("click", onToggleClick);
-              observer.disconnect();
-            };
-          };
-
-          let cleanup = installReset();
-
-          const onAstroPageLoad = () => {
-            cleanup();
-            cleanup = installReset();
-          };
-
-          document.addEventListener("astro:page-load", onAstroPageLoad);
-
-          addEventListener(
-            "pagehide",
-            () => {
-              cleanup();
-              document.removeEventListener("astro:page-load", onAstroPageLoad);
-            },
-            { once: true },
-          );
-        })();
-      </script>
-    )
-  }
-
   <div class:list={["main-frame", isSplashTemplate && "main-frame-splash"]}>
     {
       template === "splash" ? (
@@ -182,15 +143,17 @@ const isSplashTemplate = template === "splash";
     }
 
     .sidebar-pane {
-      visibility: var(--sl-sidebar-visibility, hidden);
+      border: 0;
+      margin: 0;
+      color: inherit;
+      display: none;
       position: fixed;
       z-index: var(--sl-z-index-menu);
       inset-block: var(--sl-nav-height) 0;
       inset-inline-start: 0;
       width: 100%;
       background-color: var(--background);
-      height: 100svh;
-      overflow: scroll;
+      height: calc(100svh - var(--sl-nav-height));
       overflow-y: scroll;
       overflow-x: hidden;
       scrollbar-width: none;
@@ -198,12 +161,11 @@ const isSplashTemplate = template === "splash";
       -webkit-overflow-scrolling: touch;
       overscroll-behavior: contain;
       overscroll-behavior-y: contain;
-      top: 0;
-      padding-top: calc(var(--spacing) * 18);
+      padding: 0;
     }
 
-    :global([aria-expanded="true"]) ~ .sidebar-pane {
-      --sl-sidebar-visibility: visible;
+    .sidebar-pane:popover-open {
+      display: block;
     }
 
     .sidebar-content {
@@ -219,11 +181,6 @@ const isSplashTemplate = template === "splash";
         content: "";
         padding-bottom: 1px;
       }
-
-      .sidebar-pane {
-        padding-top: 0;
-        margin-top: calc(var(--spacing) * 18);
-      }
     }
 
     .main-frame {
@@ -315,7 +272,7 @@ const isSplashTemplate = template === "splash";
         padding-inline-end: var(--sl-nav-pad-x);
       }
       .sidebar-pane {
-        --sl-sidebar-visibility: visible;
+        display: block;
         width: var(--sl-sidebar-width);
         background-color: var(--sl-color-bg-sidebar);
         border-inline-end: 1px solid var(--sl-color-hairline-shade);

package/src/overrides/PageTitle.astro

@@ -100,7 +100,7 @@ const isRtl = dir === "rtl";
       display: flex;
       justify-content: space-between;
       flex-wrap: wrap;
-      margin-top: 0.5rem;
+      margin-top: 0;
       align-items: center;
     }
     .sl-bejamas-docs-title-buttons {
@@ -129,7 +129,7 @@ const isRtl = dir === "rtl";
       font-size: 1.875rem;
       line-height: 1.2;
       font-weight: 500;
-      color: var(--sl-color-white);
+      color: var(--foreground);
     }
 
     @media (min-width: 50rem) {

package/src/overrides/TableOfContents/TableOfContentsList.astro

@@ -70,7 +70,7 @@ const { toc, isMobile = false, depth = 0 } = Astro.props;
     .isMobile a[aria-current="true"],
     .isMobile a[aria-current="true"]:hover,
     .isMobile a[aria-current="true"]:focus {
-      color: var(--sl-color-white);
+      color: var(--foreground);
       background-color: unset;
     }
     .isMobile a[aria-current="true"]::after {

package/src/overrides/ThemeProvider.astro

@@ -1,7 +1,14 @@
+---
+import { buildThemeChoiceBootstrapInlineScript } from "../lib/theme-choice";
+
+const themeChoiceBootstrapScript = buildThemeChoiceBootstrapInlineScript();
+---
+
+<script is:inline set:html={themeChoiceBootstrapScript} />
+
 {/* This is intentionally inlined to avoid FOUC. */}
 <script is:inline>
   window.StarlightThemeProvider = (() => {
-    const storageKey = "starlight-theme";
     const themeMetaMedias = [
       "(prefers-color-scheme: light)",
       "(prefers-color-scheme: dark)",
@@ -14,12 +21,12 @@
       theme === "auto" || theme === "dark" || theme === "light"
         ? theme
         : "auto";
-    const getStoredThemeChoice = () =>
-      parseTheme(
-        typeof localStorage !== "undefined" && localStorage.getItem(storageKey),
-      );
+    const getPreferredColorScheme = () =>
+      window.matchMedia("(prefers-color-scheme: light)").matches
+        ? "light"
+        : "dark";
 
-    const themeColors = (() => {
+    const readThemeColors = () => {
       const html = document.documentElement;
       const prevTheme = html.dataset.theme;
       const prevDark = html.classList.contains("dark");
@@ -45,7 +52,7 @@
       }
 
       return { light, dark };
-    })();
+    };
 
     function ensureThemeMeta(head, media) {
       const baseSelector = `meta[name="theme-color"][media="${media}"]`;
@@ -67,6 +74,7 @@
     }
 
     function syncThemeColor(theme) {
+      const themeColors = readThemeColors();
       const color = themeColors[theme];
       const head = document.head;
       if (!color || !head) return;
@@ -77,23 +85,25 @@
       });
     }
 
-    const themeChoice = getStoredThemeChoice();
     const effectiveTheme =
-      themeChoice === "auto"
-        ? window.matchMedia("(prefers-color-scheme: light)").matches
-          ? "light"
-          : "dark"
-        : themeChoice;
-    document.documentElement.dataset.theme = effectiveTheme;
-    document.documentElement.dataset.themeChoice = themeChoice;
-    document.documentElement.classList.toggle(
-      "dark",
-      effectiveTheme === "dark",
-    );
+      document.documentElement.dataset.theme === "light" ||
+      document.documentElement.dataset.theme === "dark"
+        ? document.documentElement.dataset.theme
+        : getPreferredColorScheme();
     syncThemeColor(effectiveTheme);
     return {
+      refreshThemeColors(theme) {
+        const themeChoice = parseTheme(
+          theme ?? document.documentElement.dataset.themeChoice,
+        );
+        const effectiveTheme =
+          themeChoice === "auto" ? getPreferredColorScheme() : themeChoice;
+        syncThemeColor(effectiveTheme);
+      },
       updatePickers(theme) {
-        const themeChoice = parseTheme(theme ?? getStoredThemeChoice());
+        const themeChoice = parseTheme(
+          theme ?? document.documentElement.dataset.themeChoice,
+        );
         document
           .querySelectorAll("starlight-theme-select")
           .forEach((picker) => {
@@ -110,19 +120,79 @@
                 new CustomEvent("select:set", { detail: { value: themeChoice } }),
               );
             }
-
-            /** @type {HTMLTemplateElement | null} */
-            const tmpl = document.querySelector(`#theme-icons`);
-            const newIcon =
-              tmpl && tmpl.content.querySelector("." + themeChoice);
-            if (newIcon) {
-              const oldIcon = picker.querySelector("svg.label-icon");
-              if (oldIcon) {
-                oldIcon.replaceChildren(...newIcon.cloneNode(true).childNodes);
-              }
-            }
           });
       },
     };
   })();
 </script>
+
+<script>
+  import { syncSemanticIconsInRoot } from "@bejamas/semantic-icons/browser";
+  import { refreshCurrentThemeStylesheet } from "../lib/theme-stylesheet";
+
+  const PRESET_CHANGE_EVENT = "bejamas:preset-change";
+  const SETUP_KEY = "__bejamasCurrentThemeStylesheetSync";
+  let reloadFrame = 0;
+  let pendingIconLibrary = null;
+
+  function syncDocumentIconLibrary() {
+    const renderedIcon = document.querySelector("[data-icon-library]");
+    const iconLibrary =
+      renderedIcon instanceof SVGElement
+        ? renderedIcon.dataset.iconLibrary
+        : document.documentElement.dataset.iconLibrary;
+
+    if (iconLibrary) {
+      document.documentElement.dataset.iconLibrary = iconLibrary;
+      syncSemanticIconsInRoot(document, iconLibrary);
+    }
+  }
+
+  const scheduleCurrentThemeStylesheetRefresh = () => {
+    if (reloadFrame) {
+      return;
+    }
+
+    reloadFrame = requestAnimationFrame(() => {
+      reloadFrame = 0;
+      void refreshCurrentThemeStylesheet().then(() => {
+        if (pendingIconLibrary) {
+          document.documentElement.dataset.iconLibrary = pendingIconLibrary;
+          syncSemanticIconsInRoot(document, pendingIconLibrary);
+          pendingIconLibrary = null;
+        }
+        window.StarlightThemeProvider?.refreshThemeColors?.();
+      });
+    });
+  };
+
+  if (!(SETUP_KEY in window)) {
+    window[SETUP_KEY] = true;
+    syncDocumentIconLibrary();
+
+    window.addEventListener("theme-toggle-changed", (event) => {
+      const themeChoice =
+        event instanceof CustomEvent && typeof event.detail?.themeChoice === "string"
+          ? event.detail.themeChoice
+          : undefined;
+
+      window.StarlightThemeProvider?.refreshThemeColors?.(themeChoice);
+    });
+
+    window.addEventListener(PRESET_CHANGE_EVENT, (event) => {
+      const presetChange = event;
+
+      pendingIconLibrary =
+        presetChange instanceof CustomEvent &&
+        typeof presetChange.detail?.iconLibrary === "string"
+          ? presetChange.detail.iconLibrary
+          : null;
+
+      scheduleCurrentThemeStylesheetRefresh();
+    });
+    document.addEventListener("astro:after-swap", () => {
+      window.StarlightThemeProvider?.refreshThemeColors?.();
+      syncDocumentIconLibrary();
+    });
+  }
+</script>

package/src/overrides/ThemeSelect.astro

@@ -36,61 +36,46 @@ import { SunIcon, MoonIcon, LaptopIcon } from "@lucide/astro";
   </div>
 </starlight-theme-select>
 
-<script is:inline>
-  StarlightThemeProvider.updatePickers();
-</script>
-
 <script>
-  type Theme = "auto" | "dark" | "light";
-  const storageKey = "starlight-theme";
-
-  const parseTheme = (theme: unknown): Theme =>
-    theme === "auto" || theme === "dark" || theme === "light" ? theme : "auto";
-
-  const loadTheme = (): Theme =>
-    parseTheme(
-      typeof localStorage !== "undefined" && localStorage.getItem(storageKey),
-    );
-
-  function storeTheme(theme: Theme): void {
-    if (typeof localStorage !== "undefined") {
-      localStorage.setItem(
-        storageKey,
-        theme === "light" || theme === "dark" ? theme : "",
-      );
-    }
-  }
+  import {
+    getThemeChoiceFromRoot,
+    parseStoredThemeChoice,
+    setThemeChoice,
+    syncThemeChoiceControls,
+  } from "../lib/theme-choice";
 
-  const getPreferredColorScheme = (): Theme =>
-    matchMedia("(prefers-color-scheme: light)").matches ? "light" : "dark";
+  class StarlightThemeSelect extends HTMLElement {
+    private selectRoot: HTMLElement | null = null;
 
-  function onThemeChange(theme: Theme): void {
-    const resolved = theme === "auto" ? getPreferredColorScheme() : theme;
-    StarlightThemeProvider.updatePickers(theme);
-    document.documentElement.dataset.theme = resolved;
-    document.documentElement.dataset.themeChoice = theme;
-    document.documentElement.classList.toggle("dark", resolved === "dark");
-    storeTheme(theme);
-  }
+    private onSelectChange = (event: Event) => {
+      const value = (event as CustomEvent<{ value?: unknown }>).detail?.value;
+      if (typeof value !== "string") return;
 
-  matchMedia("(prefers-color-scheme: light)").addEventListener("change", () => {
-    if (loadTheme() === "auto") onThemeChange("auto");
-  });
+      const nextTheme = parseStoredThemeChoice(value);
+      const currentTheme = getThemeChoiceFromRoot(document.documentElement);
+      if (nextTheme === currentTheme) return;
 
-  class StarlightThemeSelect extends HTMLElement {
-    constructor() {
-      super();
-      onThemeChange(loadTheme());
-      const select = this.querySelector("#starlight-theme-select");
-      select?.addEventListener("select:change", (e) => {
-        if (e.detail.value) {
-          onThemeChange(parseTheme(e.detail.value));
-        }
-      });
+      setThemeChoice(nextTheme);
+    };
+
+    connectedCallback() {
+      this.selectRoot = this.querySelector<HTMLElement>("#starlight-theme-select");
+      syncThemeChoiceControls(
+        getThemeChoiceFromRoot(document.documentElement),
+        this,
+      );
+      this.selectRoot?.addEventListener("select:change", this.onSelectChange);
+    }
+
+    disconnectedCallback() {
+      this.selectRoot?.removeEventListener("select:change", this.onSelectChange);
+      this.selectRoot = null;
     }
   }
 
-  customElements.define("starlight-theme-select", StarlightThemeSelect);
+  if (!customElements.get("starlight-theme-select")) {
+    customElements.define("starlight-theme-select", StarlightThemeSelect);
+  }
 </script>
 
 <style>