starlight-theme-bejamas 0.0.0-canary.0138fd3

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");
+  });
+});

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/lib/utils.ts

@@ -0,0 +1,6 @@
+import { type ClassValue, clsx } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}

package/src/lib/vite.ts

@@ -0,0 +1,62 @@
+import type { ViteUserConfig } from "astro";
+import type { StarlightThemeBejamasConfig } from "../config";
+
+export function vitePluginStarlightThemeBejamas(
+  config: StarlightThemeBejamasConfig,
+): VitePlugin {
+  const moduleId = "virtual:starlight-theme-bejamas/user-config";
+  const resolvedModuleId = `\0${moduleId}`;
+  const moduleContent = `export default ${JSON.stringify(config)}`;
+
+  const componentsPrefix = "virtual:starlight-theme-bejamas/components/";
+  const resolvedComponentsPrefix = `\0${componentsPrefix}`;
+
+  return {
+    name: "vite-plugin-starlight-theme-bejamas",
+    load(id) {
+      if (id === resolvedModuleId) {
+        return moduleContent;
+      }
+
+      if (id.startsWith(resolvedComponentsPrefix)) {
+        const componentId = id.slice(resolvedComponentsPrefix.length);
+        const componentName = componentId.replace(/\.astro$/, "");
+        const target = config.components?.[componentName];
+
+        if (!target) {
+          return `export default (()=>{ throw new Error(\"starlight-theme-bejamas: No component mapping found for '${componentName}'. Add it under 'components' in your starlightThemeBejamas config.\"); })()`;
+        }
+
+        // Check if target is a barrel import (no .astro extension) or old-style file import
+        const isBarrelImport = !target.endsWith(".astro");
+
+        if (isBarrelImport) {
+          // For barrel imports, the component is exported as a named export in PascalCase
+          // Convert componentName (e.g., 'button') to PascalCase (e.g., 'Button')
+          const pascalCaseName = componentName.charAt(0).toUpperCase() + componentName.slice(1);
+          return `export { ${pascalCaseName} as default, ${pascalCaseName} } from "${target}"; export * from "${target}";`;
+        }
+
+        // Old pattern: .astro file with default export
+        return `export { default } from "${target}"; export * from "${target}";`;
+      }
+
+      return undefined;
+    },
+    resolveId(id) {
+      if (id === moduleId) {
+        return resolvedModuleId;
+      }
+
+      if (id.startsWith(componentsPrefix)) {
+        const componentId = id.slice(componentsPrefix.length);
+        const componentName = componentId.replace(/\.astro$/, "");
+        return `${resolvedComponentsPrefix}${componentName}`;
+      }
+
+      return undefined;
+    },
+  };
+}
+
+type VitePlugin = NonNullable<ViteUserConfig["plugins"]>[number];

package/src/overrides/Footer.astro

@@ -0,0 +1,143 @@
+---
+import EditLink from "virtual:starlight/components/EditLink";
+import LastUpdated from "virtual:starlight/components/LastUpdated";
+import Pagination from "virtual:starlight/components/Pagination";
+import config from "virtual:starlight/user-config";
+---
+
+<footer class="sl-flex footer-wide">
+  <div class="meta"><EditLink /><LastUpdated /></div>
+  <Pagination />
+  <div class="fade"></div>
+</footer>
+
+{
+  config.credits && (
+    <div class="kudos sl-flex footer-wide">
+      <p>
+        Built at <a href="https://bejamas.com?utm_source=ui">Bejamas</a>. The
+        source code is available on{" "}
+        <a href="https://github.com/bejamas/ui">GitHub</a>.
+      </p>
+    </div>
+  )
+}
+
+<style>
+  @layer starlight.core {
+    .footer-wide {
+      width: calc(
+        100% + calc(var(--sl-content-pad-x) * 2) + calc(var(--spacing) * 2)
+      );
+      margin-inline: calc(var(--spacing) * -1 - var(--sl-content-pad-x));
+      padding-inline: calc(var(--sl-content-pad-x) + var(--spacing));
+    }
+
+    footer {
+      flex-direction: column;
+      gap: 1.5rem;
+      position: sticky;
+      bottom: 0;
+      background: linear-gradient(to top, var(--background), transparent);
+      padding-block: calc(var(--spacing) * 3);
+      z-index: 10;
+    }
+
+    @media (min-width: 50rem) {
+      footer {
+        position: relative;
+        background: transparent;
+      }
+      .meta {
+        display: flex;
+      }
+      .kudos {
+        margin-bottom: calc(var(--spacing) * -10);
+      }
+    }
+
+    .meta {
+      gap: 0.75rem 3rem;
+      justify-content: space-between;
+      flex-wrap: wrap;
+      margin-top: 3rem;
+      font-size: var(--sl-text-sm);
+      color: var(--sl-color-gray-3);
+      display: flex;
+    }
+
+    .meta:empty {
+      display: none;
+    }
+
+    .meta > :global(p:only-child) {
+      margin-inline-start: auto;
+    }
+
+    .kudos {
+      align-items: center;
+      gap: 0.5em;
+      margin-block: 0;
+      font-size: var(--sl-text-xs);
+      color: var(--muted-foreground);
+      justify-content: center;
+      padding-top: calc(var(--spacing) * 12);
+      padding-bottom: 0;
+      background-color: var(--background);
+      justify-content: center;
+    }
+    .kudos a {
+      color: var(--muted-foreground);
+      text-decoration: underline;
+      text-underline-offset: 0.1875rem;
+    }
+    .kudos a:hover {
+      color: var(--foreground);
+    }
+
+    @media (min-width: 50rem) {
+      .kudos {
+        background-color: transparent;
+      }
+    }
+
+    .fade {
+      --blur: 4px;
+      --stop: 50%;
+      --height: 72px;
+      position: absolute;
+      pointer-events: none;
+      width: 100%;
+      height: var(--height);
+      user-select: none;
+      -webkit-user-select: none;
+      left: 0;
+      -webkit-backdrop-filter: blur(var(--blur));
+      backdrop-filter: blur(var(--blur));
+
+      background: linear-gradient(
+        to bottom,
+        transparent,
+        var(--sl-page-background)
+      );
+      mask-image: linear-gradient(
+        to top,
+        var(--sl-page-background) var(--stop),
+        transparent
+      );
+      bottom: 0;
+    }
+
+    @media (min-width: 50rem) {
+      .fade {
+        display: none;
+      }
+    }
+  }
+
+  @layer starlight.components {
+    .kudos :global(svg) {
+      color: var(--sl-color-orange);
+    }
+  }
+</style>