@nu-appdev/northwestern-starlight-theme 1.1.1 → 1.3.0

package/src/scripts/mermaid/toolbar.ts

@@ -0,0 +1,137 @@
+/**
+ * Mermaid toolbar entry point.
+ *
+ * Orchestrates diagram rendering, toolbar injection, and lifecycle management
+ * across page loads, theme changes, and Astro view transitions.
+ */
+
+declare global {
+    interface Window {
+        /** Whether the hover toolbar is enabled (injected by the Northwestern Mermaid integration). */
+        __NU_MERMAID_TOOLBAR__?: boolean;
+        /** Northwestern Mermaid theme configs for light and dark modes. */
+        __NU_MERMAID_CONFIGS__?: {
+            light?: Record<string, unknown>;
+            dark?: Record<string, unknown>;
+        };
+    }
+}
+
+import { openFullscreen } from "./fullscreen";
+import { diagramSources, renderAllDiagrams } from "./render";
+import { createActionButton, downloadDiagramSvg, flashSuccess, ICON_PATHS, writeToClipboard } from "./ui";
+
+/** Maximum time (ms) to watch for lazy-rendered diagrams before disconnecting the observer. */
+const TOOLBAR_OBSERVER_TIMEOUT_MS = 30_000;
+
+/**
+ * Inject hover toolbars into rendered mermaid diagrams.
+ *
+ * Safe to call repeatedly across page loads, lazy render callbacks, theme changes,
+ * and Astro view transitions.
+ *
+ * **Idempotency guards:**
+ * - Skips fullscreen clones (`.nu-mermaid-fullscreen`)
+ * - Skips diagrams without a rendered `<svg>` child
+ * - Skips diagrams that already have a `.nu-mermaid-toolbar`
+ */
+function injectToolbars(): number {
+    const diagrams = document.querySelectorAll<HTMLElement>(".mermaid");
+    if (!diagrams.length) return 0;
+
+    let injectedCount = 0;
+
+    diagrams.forEach((container) => {
+        if (container.classList.contains("nu-mermaid-fullscreen")) return;
+        if (!container.querySelector("svg")) return;
+        if (container.querySelector(".nu-mermaid-toolbar")) return;
+
+        const toolbar = document.createElement("div");
+        toolbar.className = "nu-mermaid-toolbar";
+
+        toolbar.appendChild(createActionButton("Fullscreen", "fullscreen", ICON_PATHS.fullscreen));
+        toolbar.appendChild(createActionButton("Download SVG", "download-svg", ICON_PATHS.download));
+
+        const source = diagramSources.get(container);
+        if (source) {
+            toolbar.appendChild(createActionButton("Copy Mermaid", "copy-source", ICON_PATHS.code));
+        }
+
+        container.style.position = "relative";
+        container.appendChild(toolbar);
+        injectedCount++;
+
+        toolbar.addEventListener("click", (event) => {
+            const button = (event.target as HTMLElement).closest<HTMLButtonElement>(".nu-mermaid-btn");
+            if (!button) return;
+            event.stopPropagation();
+
+            const svg = container.querySelector("svg");
+            if (!svg) return;
+
+            const isKeyboardActivated = event.detail === 0;
+
+            switch (button.dataset.action) {
+                case "fullscreen":
+                    openFullscreen(svg, container, button, isKeyboardActivated);
+                    break;
+                case "download-svg":
+                    downloadDiagramSvg(svg, container);
+                    flashSuccess(button, "Downloaded!");
+                    break;
+                case "copy-source":
+                    if (source) writeToClipboard(source, button);
+                    break;
+            }
+        });
+    });
+
+    return injectedCount;
+}
+
+function isToolbarEnabled(): boolean {
+    return window.__NU_MERMAID_TOOLBAR__ !== false;
+}
+
+/**
+ * Render diagrams and inject toolbars. Called on initial page load
+ * and after Astro view transitions.
+ */
+let domObserver: MutationObserver | undefined;
+
+function onPageReady(): void {
+    domObserver?.disconnect();
+
+    void renderAllDiagrams(false).then(() => {
+        if (isToolbarEnabled()) injectToolbars();
+
+        // Watch for lazy-rendered diagrams that enter the viewport after initial load
+        domObserver = new MutationObserver(() => {
+            if (isToolbarEnabled()) injectToolbars();
+        });
+        domObserver.observe(document.body, { childList: true, subtree: true });
+        setTimeout(() => domObserver?.disconnect(), TOOLBAR_OBSERVER_TIMEOUT_MS);
+    });
+}
+
+// Re-render all diagrams and re-inject toolbars when the theme changes
+const themeObserver = new MutationObserver(() => {
+    void renderAllDiagrams(true).then(() => {
+        if (isToolbarEnabled()) injectToolbars();
+    });
+});
+
+themeObserver.observe(document.documentElement, {
+    attributes: true,
+    attributeFilter: ["data-theme"],
+});
+
+// Initial page load
+if (document.readyState === "loading") {
+    document.addEventListener("DOMContentLoaded", onPageReady);
+} else {
+    onPageReady();
+}
+
+// Astro view transitions
+document.addEventListener("astro:page-load", onPageReady);

package/src/scripts/mermaid/ui.ts

@@ -0,0 +1,265 @@
+/**
+ * Shared UI primitives for the Mermaid toolbar and fullscreen viewer.
+ *
+ * Pure factories and helpers with no DOM querying or lifecycle logic.
+ * Everything here is stateless except the success timer and toast tracking,
+ * which are scoped to individual button/container instances.
+ */
+
+import { diagramSources } from "./render";
+
+// ---------------------------------------------------------------------------
+// SVG icon paths (Lucide-compatible, 24x24 viewBox)
+// ---------------------------------------------------------------------------
+
+/** SVG path data for toolbar and overlay icons. */
+export const ICON_PATHS = {
+    fullscreen: ["M8 3H5a2 2 0 00-2 2v3m18 0V5a2 2 0 00-2-2h-3m0 18h3a2 2 0 002-2v-3M3 16v3a2 2 0 002 2h3"],
+    download: ["M21 15v4a2 2 0 01-2 2H5a2 2 0 01-2-2v-4", "M7 10l5 5 5-5", "M12 15V3"],
+    close: ["M18 6L6 18M6 6l12 12"],
+    zoomIn: ["M12 5v14", "M5 12h14"],
+    zoomOut: ["M5 12h14"],
+    reset: ["M3 12a9 9 0 1018 0 9 9 0 00-18 0z", "M12 8v4l2 2"],
+    copy: [
+        "M8 4H6a2 2 0 00-2 2v12a2 2 0 002 2h8a2 2 0 002-2v-2",
+        "M16 4h2a2 2 0 012 2v6a2 2 0 01-2 2h-8a2 2 0 01-2-2V6a2 2 0 012-2",
+    ],
+    code: ["M16 18l6-6-6-6", "M8 6l-6 6 6 6"],
+    check: ["M20 6L9 17l-5-5"],
+} as const;
+
+const SVG_NS = "http://www.w3.org/2000/svg";
+
+// ---------------------------------------------------------------------------
+// Icon and button factories
+// ---------------------------------------------------------------------------
+
+/** Create a stroked SVG icon from an array of path `d` attributes. */
+export function createIcon(paths: readonly string[], size = 14): SVGElement {
+    const svg = document.createElementNS(SVG_NS, "svg");
+    const attrs: Record<string, string | number> = {
+        width: size,
+        height: size,
+        viewBox: "0 0 24 24",
+        fill: "none",
+        stroke: "currentColor",
+        "stroke-width": "2",
+        "stroke-linecap": "round",
+        "stroke-linejoin": "round",
+    };
+    for (const [attr, value] of Object.entries(attrs)) {
+        svg.setAttribute(attr, String(value));
+    }
+    for (const d of paths) {
+        const path = document.createElementNS(SVG_NS, "path");
+        path.setAttribute("d", d);
+        svg.appendChild(path);
+    }
+    return svg;
+}
+
+/** Create a zoom-specific icon with a magnifying glass circle + handle. */
+function createZoomIcon(innerPaths: readonly string[]): SVGElement {
+    const svg = createIcon(innerPaths, 14);
+    const circle = document.createElementNS(SVG_NS, "circle");
+    circle.setAttribute("cx", "11");
+    circle.setAttribute("cy", "11");
+    circle.setAttribute("r", "8");
+    svg.insertBefore(circle, svg.firstChild);
+    const handle = document.createElementNS(SVG_NS, "path");
+    handle.setAttribute("d", "M21 21l-4.35-4.35");
+    svg.insertBefore(handle, svg.children[1]);
+    return svg;
+}
+
+/** Create an accessible toolbar button with an icon and a `data-action` attribute. */
+export function createActionButton(
+    label: string,
+    action: string,
+    iconPaths: readonly string[],
+    className = "nu-mermaid-btn",
+): HTMLButtonElement {
+    const button = document.createElement("button");
+    button.className = className;
+    button.dataset.action = action;
+    button.title = label;
+    button.setAttribute("aria-label", label);
+    button.appendChild(createIcon(iconPaths));
+    return button;
+}
+
+/** Create a zoom-specific button with a magnifying glass icon. */
+export function createZoomButton(
+    label: string,
+    action: string,
+    innerPaths: readonly string[],
+    className = "nu-mermaid-btn",
+): HTMLButtonElement {
+    const button = document.createElement("button");
+    button.className = className;
+    button.dataset.action = action;
+    button.title = label;
+    button.setAttribute("aria-label", label);
+    button.appendChild(createZoomIcon(innerPaths));
+    return button;
+}
+
+// ---------------------------------------------------------------------------
+// Button success feedback
+// ---------------------------------------------------------------------------
+
+const activeSuccessTimers = new WeakMap<HTMLButtonElement, number>();
+
+/**
+ * Temporarily replace a button's icon with a checkmark and apply the success style.
+ *
+ * Debounced per button — rapid clicks clear the previous timer and restart.
+ * The original icon and title restore after 1500ms.
+ */
+export function flashSuccess(button: HTMLButtonElement, label = "Copied!"): void {
+    const previousTimer = activeSuccessTimers.get(button);
+    if (previousTimer) {
+        clearTimeout(previousTimer);
+        button.querySelector(".nu-mermaid-check")?.remove();
+    }
+
+    const originalTitle = button.title;
+    const originalIcon = button.querySelector("svg:not(.nu-mermaid-check)");
+    const checkIcon = createIcon(ICON_PATHS.check, 14);
+    checkIcon.classList.add("nu-mermaid-check");
+
+    button.title = label;
+    button.classList.add("nu-mermaid-success");
+    if (originalIcon) {
+        (originalIcon as HTMLElement).style.display = "none";
+        button.insertBefore(checkIcon, button.firstChild);
+    }
+
+    const timer = window.setTimeout(() => {
+        activeSuccessTimers.delete(button);
+        button.title = originalTitle;
+        button.classList.remove("nu-mermaid-success");
+        checkIcon.remove();
+        if (originalIcon) (originalIcon as HTMLElement).style.display = "";
+    }, 1500);
+    activeSuccessTimers.set(button, timer);
+}
+
+// ---------------------------------------------------------------------------
+// Toast notifications
+// ---------------------------------------------------------------------------
+
+let currentToast: HTMLElement | null = null;
+let currentToastTimer = 0;
+
+/** Display a toast message in the bottom-right of a container. Replaces any active toast. */
+export function showToast(container: HTMLElement, message: string): void {
+    if (currentToast) {
+        clearTimeout(currentToastTimer);
+        currentToast.remove();
+    }
+
+    const toast = document.createElement("div");
+    toast.className = "nu-mermaid-toast";
+    toast.textContent = message;
+    container.appendChild(toast);
+    currentToast = toast;
+
+    requestAnimationFrame(() => toast.classList.add("nu-mermaid-toast-visible"));
+
+    currentToastTimer = window.setTimeout(() => {
+        toast.classList.remove("nu-mermaid-toast-visible");
+        setTimeout(() => {
+            toast.remove();
+            if (currentToast === toast) currentToast = null;
+        }, 200);
+    }, 2000);
+}
+
+// ---------------------------------------------------------------------------
+// Clipboard
+// ---------------------------------------------------------------------------
+
+/**
+ * Copy text to the clipboard with a visual success flash on the button.
+ *
+ * Uses the Clipboard API when available (HTTPS / localhost). Falls back to
+ * `document.execCommand("copy")` via a hidden textarea for insecure contexts
+ * (e.g., HTTP over LAN). The textarea is appended inside the closest overlay
+ * to prevent iOS Safari's URL bar from toggling.
+ */
+export async function writeToClipboard(text: string, triggerButton: HTMLButtonElement): Promise<void> {
+    try {
+        await navigator.clipboard.writeText(text);
+        flashSuccess(triggerButton, "Copied!");
+    } catch {
+        const host = triggerButton.closest(".nu-mermaid-overlay") ?? document.body;
+        const textarea = document.createElement("textarea");
+        textarea.value = text;
+        textarea.setAttribute("readonly", "");
+        textarea.style.cssText = "position:absolute;left:-9999px;opacity:0;height:0";
+        host.appendChild(textarea);
+        textarea.select();
+        const success = document.execCommand("copy");
+        textarea.remove();
+        if (success) flashSuccess(triggerButton, "Copied!");
+    }
+}
+
+// ---------------------------------------------------------------------------
+// SVG download
+// ---------------------------------------------------------------------------
+
+/**
+ * Download the diagram SVG with a descriptive filename derived from
+ * the site title, page slug, and diagram type.
+ */
+export function downloadDiagramSvg(svg: SVGElement, container: Element): void {
+    const clone = svg.cloneNode(true) as SVGElement;
+    clone.setAttribute("xmlns", SVG_NS);
+    const blob = new Blob([clone.outerHTML], { type: "image/svg+xml" });
+    const url = URL.createObjectURL(blob);
+    const anchor = document.createElement("a");
+    anchor.href = url;
+    anchor.download = buildDownloadFilename(container);
+    anchor.click();
+    URL.revokeObjectURL(url);
+}
+
+// ---------------------------------------------------------------------------
+// Filename generation (private)
+// ---------------------------------------------------------------------------
+
+function slugify(text: string): string {
+    return text
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-|-$/g, "");
+}
+
+function extractSiteSlug(): string {
+    const segments = document.title.split("|");
+    return slugify((segments.length > 1 ? segments.at(-1)! : segments[0]).trim());
+}
+
+function extractPageSlug(): string {
+    return slugify(window.location.pathname.replace(/^\/|\/$/g, "")) || "index";
+}
+
+function detectDiagramType(container: Element): string {
+    const source = diagramSources.get(container) ?? "";
+    const keyword = source.trim().split(/[\s\n]/)[0];
+    return slugify(keyword.replace(/[-_](v\d+|beta)$/i, "").replace(/(diagram|chart)$/i, "")) || "diagram";
+}
+
+function buildDownloadFilename(container: Element): string {
+    const site = extractSiteSlug();
+    const page = extractPageSlug();
+    const type = detectDiagramType(container);
+
+    const allDiagrams = [...document.querySelectorAll<HTMLElement>(".mermaid:not(.nu-mermaid-fullscreen)")];
+    const sameType = allDiagrams.filter((d) => detectDiagramType(d) === type);
+    const disambiguator = sameType.length > 1 ? `-${sameType.indexOf(container as HTMLElement) + 1}` : "";
+
+    return `${site}_${page}-${type}${disambiguator}.svg`;
+}

package/src/styles/a11y.css

@@ -0,0 +1,69 @@
+/* ==========================================================================
+   Accessibility — High contrast and reduced transparency overrides
+   ========================================================================== */
+
+@layer northwestern {
+    @media (prefers-contrast: more) {
+        :root,
+        ::backdrop {
+            --nu-border-color: CanvasText;
+            --nu-color-text-muted: CanvasText;
+            --nu-focus-ring: Highlight;
+            --nu-focus-border: Highlight;
+            --nu-focus-shadow-color: transparent;
+            --nu-hover-bg: Mark;
+        }
+
+        :root[data-theme="light"],
+        [data-theme="light"] ::backdrop {
+            --nu-border-color: CanvasText;
+            --nu-color-text-muted: CanvasText;
+            --nu-focus-ring: Highlight;
+        }
+
+        .sl-markdown-content table:not(:where(.not-content *)) > thead > tr > th,
+        .sl-markdown-content table:not(:where(.not-content *)) > tbody > tr > td {
+            border-width: 2px;
+        }
+
+        .starlight-aside {
+            border-width: 2px !important;
+        }
+
+        .sl-markdown-content blockquote:not(:where(.not-content *)) {
+            border-inline-start-width: 6px;
+        }
+
+        .sl-badge {
+            border-width: 2px;
+        }
+    }
+
+    @media (prefers-reduced-transparency: reduce) {
+        :root,
+        ::backdrop {
+            --nu-purple-tint: var(--nu-purple-10);
+            --nu-purple-tint-strong: var(--nu-purple-20);
+            --nu-purple-surface: #f3f0f7;
+            --nu-purple-surface-subtle: #f7f5f9;
+            --nu-surface-muted: #f5f5f5;
+            --nu-hover-bg: #ebebeb;
+        }
+
+        :root:not([data-theme="light"]),
+        :root:not([data-theme="light"]) ::backdrop {
+            --nu-purple-surface: #2a2235;
+            --nu-purple-surface-subtle: #231d2e;
+            --nu-surface-muted: #262626;
+            --nu-hover-bg: #333;
+        }
+
+        .sl-markdown-content blockquote:not(:where(.not-content *)) {
+            background: var(--nu-purple-surface);
+        }
+
+        :root:not([data-theme="light"]) .sl-markdown-content blockquote:not(:where(.not-content *)) {
+            background: var(--nu-purple-surface);
+        }
+    }
+}

package/src/styles/components/blockquotes.css

@@ -0,0 +1,37 @@
+/* ==========================================================================
+   Blockquotes — Styled quotations with cite/footer support
+   ========================================================================== */
+
+@layer northwestern {
+    .sl-markdown-content blockquote:not(:where(.not-content *)) {
+        padding: 1rem 1.5rem;
+        margin: 2rem 0;
+        color: var(--nu-color-text);
+        background: rgb(228 224 238 / 42%);
+        border-inline-start: 10px solid var(--nu-purple-100);
+    }
+
+    .sl-markdown-content blockquote:not(:where(.not-content *)) p:last-child {
+        margin-bottom: 0;
+    }
+
+    .sl-markdown-content blockquote:not(:where(.not-content *)) cite,
+    .sl-markdown-content blockquote:not(:where(.not-content *)) footer {
+        display: block;
+        margin-top: 0.75rem;
+        font-size: var(--sl-text-sm);
+        font-style: normal;
+        font-weight: 700;
+        color: var(--nu-color-link);
+    }
+
+    :root:not([data-theme="light"]) .sl-markdown-content blockquote:not(:where(.not-content *)) {
+        background: rgb(48 16 78 / 35%);
+        border-inline-start-color: var(--nu-purple-40);
+    }
+
+    :root:not([data-theme="light"]) .sl-markdown-content blockquote:not(:where(.not-content *)) cite,
+    :root:not([data-theme="light"]) .sl-markdown-content blockquote:not(:where(.not-content *)) footer {
+        color: var(--nu-purple-30);
+    }
+}

package/src/styles/components/code.css

@@ -35,10 +35,6 @@
         font-weight: 600;
     }
 
-    .expressive-code .copy button {
-        border-radius: 0;
-    }
-
     .expressive-code .frame.has-title:not(.is-terminal) .header {
         display: flex;
         align-items: end;
@@ -77,7 +73,6 @@
         height: 6px;
         content: "";
         background-color: #bbb4c7;
-        border-radius: 999px;
         box-shadow:
             10px 0 0 #bbb4c7,
             20px 0 0 #bbb4c7;
@@ -134,6 +129,10 @@
         color: #6e6e6e;
     }
 
+    :root:not([data-theme="light"]) .expressive-code .gutter .ln {
+        color: #999;
+    }
+
     :root:not([data-theme="light"]) .expressive-code .frame {
         border-top-color: var(--nu-purple-40);
         box-shadow: none;
@@ -165,4 +164,8 @@
         background: rgb(41 41 41 / 95%);
         border-color: var(--nu-purple-40);
     }
+
+    :root:not([data-theme="light"]) .expressive-code .copy button:hover::after {
+        background-color: var(--nu-purple-40);
+    }
 }

package/src/styles/components/footnotes.css

@@ -0,0 +1,76 @@
+/* ==========================================================================
+   Footnotes — GFM footnote references, section, and back-references
+   ========================================================================== */
+
+@layer northwestern {
+    .sl-markdown-content a[data-footnote-ref] {
+        font-weight: 600;
+        line-height: 1;
+        vertical-align: super;
+        color: var(--sl-color-accent);
+        text-decoration: none;
+    }
+
+    .sl-markdown-content a[data-footnote-ref]::before {
+        content: "[";
+    }
+
+    .sl-markdown-content a[data-footnote-ref]::after {
+        content: "]";
+    }
+
+    .sl-markdown-content a[data-footnote-ref]:hover {
+        text-decoration: underline;
+    }
+
+    /* Footnotes section */
+    .sl-markdown-content section[data-footnotes] {
+        padding-top: 1.5rem;
+        margin-top: 2.5rem;
+        font-size: 0.875rem;
+        color: var(--nu-color-text-muted);
+        border-top: 1px solid var(--nu-border-color);
+    }
+
+    .sl-markdown-content section[data-footnotes] > :first-child:is(hr) {
+        display: none;
+    }
+
+    .sl-markdown-content section[data-footnotes] > .sl-heading-wrapper {
+        position: absolute;
+        width: 1px;
+        height: 1px;
+        padding: 0;
+        margin: -1px;
+        overflow: hidden;
+        white-space: nowrap;
+        border: 0;
+        clip-path: inset(50%);
+    }
+
+    .sl-markdown-content section[data-footnotes] ol {
+        padding-left: 1.5rem;
+    }
+
+    .sl-markdown-content section[data-footnotes] li {
+        padding-left: 0.25rem;
+    }
+
+    .sl-markdown-content section[data-footnotes] li + li {
+        margin-top: 0.5rem;
+    }
+
+    .sl-markdown-content section[data-footnotes] a[data-footnote-backref] {
+        margin-left: 0.25em;
+        font-family: "Segoe UI Symbol", "Noto Sans Symbols 2", sans-serif;
+        font-size: 1em;
+        font-weight: 700;
+        color: var(--sl-color-accent);
+        text-decoration: none;
+        font-variant-emoji: text;
+    }
+
+    .sl-markdown-content section[data-footnotes] a[data-footnote-backref]:hover {
+        border-bottom: 1px solid var(--sl-color-accent);
+    }
+}

package/src/styles/components/kbd.css

@@ -0,0 +1,69 @@
+/* ==========================================================================
+   Kbd — Keyboard shortcut display
+   ========================================================================== */
+
+/* stylelint-disable selector-class-pattern */
+
+@layer northwestern {
+    .nu-kbd {
+        display: inline-flex;
+        gap: 0.25rem;
+        align-items: center;
+        font-family: var(--sl-font-system-mono);
+        font-size: var(--sl-text-xs);
+        line-height: 1;
+        white-space: nowrap;
+        background: none;
+        border: none;
+    }
+
+    .nu-kbd__key {
+        display: inline-flex;
+        align-items: center;
+        justify-content: center;
+        min-width: 1.375rem;
+        height: 1.375rem;
+        padding: 0 0.3125rem;
+        font-family: inherit;
+        font-size: inherit;
+        font-weight: 500;
+        line-height: 1;
+        color: var(--nu-color-text);
+        text-align: center;
+        background-color: var(--nu-purple-surface-subtle);
+        border: 1px solid rgb(78 42 132 / 18%);
+        border-bottom-width: 2px;
+        border-radius: 3px !important;
+    }
+
+    :root:not([data-theme="light"]) .nu-kbd__key {
+        color: var(--nu-color-text);
+        background-color: rgb(255 255 255 / 6%);
+        border-color: rgb(255 255 255 / 12%);
+    }
+
+    .nu-kbd__sep {
+        font-size: 0.625rem;
+        color: var(--nu-color-text-muted);
+        user-select: none;
+    }
+
+    .nu-kbd__mac,
+    .nu-kbd__other {
+        display: inline-flex;
+        gap: 0.25rem;
+        align-items: center;
+    }
+
+    .nu-kbd__other {
+        display: none;
+    }
+
+    :root[data-platform="other"] .nu-kbd__mac {
+        display: none;
+    }
+
+    :root[data-platform="other"] .nu-kbd__other {
+        display: inline-flex;
+    }
+}