@nu-appdev/northwestern-starlight-theme 1.0.0

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@nu-appdev/northwestern-starlight-theme",
+  "version": "1.0.0",
+  "description": "A Northwestern-branded theme for Astro Starlight",
+  "license": "MIT",
+  "author": "Danny Foster <danny@northwestern.edu>",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/NIT-Administrative-Systems/northwestern-starlight-theme.git",
+    "directory": "packages/northwestern-starlight-theme"
+  },
+  "homepage": "https://starlight-theme.entapp.northwestern.edu",
+  "bugs": {
+    "url": "https://github.com/NIT-Administrative-Systems/northwestern-starlight-theme/issues"
+  },
+  "keywords": [
+    "astro",
+    "starlight",
+    "theme",
+    "northwestern",
+    "documentation",
+    "plugin"
+  ],
+  "type": "module",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "exports": {
+    ".": "./index.ts",
+    "./expressive-code": "./expressive-code.mjs",
+    "./mermaid": "./mermaid.ts",
+    "./src/styles/components/*": "./src/styles/components/*",
+    "./src/components/*": "./src/components/*",
+    "./src/scripts/*": "./src/scripts/*",
+    "./src/styles/*": "./src/styles/*"
+  },
+  "files": [
+    "CHANGELOG.md",
+    "expressive-code.mjs",
+    "index.ts",
+    "mermaid.ts",
+    "src/"
+  ],
+  "dependencies": {
+    "@expressive-code/plugin-line-numbers": "^0.41.7",
+    "khroma": "^2.1.0"
+  },
+  "peerDependencies": {
+    "@astrojs/starlight": ">=0.32.0",
+    "astro": ">=5.1.5",
+    "astro-mermaid": ">=1.3.0",
+    "mermaid": ">=11.0.0"
+  },
+  "peerDependenciesMeta": {
+    "astro-mermaid": {
+      "optional": true
+    },
+    "mermaid": {
+      "optional": true
+    }
+  }
+}

package/src/components/ConditionalEditLink.astro

@@ -0,0 +1,7 @@
+---
+import EditLink from "@astrojs/starlight/components/EditLink.astro";
+
+const isHomepage = Astro.locals.starlightRoute.id === "";
+---
+
+{isHomepage ? <div /> : <EditLink {...Astro.props} />}

package/src/components/Hero.astro

@@ -0,0 +1,252 @@
+---
+import { Image } from "astro:assets";
+import themeConfig from "virtual:northwestern-theme/config";
+import { LinkButton } from "@astrojs/starlight/components";
+
+const PAGE_TITLE_ID = "_top";
+const { data } = Astro.locals.starlightRoute.entry;
+const { title = data.title, tagline, image, actions = [] } = data.hero || {};
+
+const imageAttrs = {
+    loading: "eager" as const,
+    decoding: "async" as const,
+    width: 400,
+    height: 400,
+    alt: image?.alt || "",
+};
+
+let darkImage: ImageMetadata | undefined;
+let lightImage: ImageMetadata | undefined;
+let rawHtml: string | undefined;
+if (image) {
+    if ("file" in image) {
+        darkImage = image.file;
+    } else if ("dark" in image) {
+        darkImage = image.dark;
+        lightImage = image.light;
+    } else {
+        rawHtml = image.html;
+    }
+}
+
+const hasImage = Boolean(darkImage || lightImage || rawHtml);
+const isSplit = hasImage && themeConfig.homepage.layout === "split";
+const showTitle = themeConfig.homepage.showTitle;
+---
+
+<div class:list={["hero", { "hero--split": isSplit }]}>
+    {
+        isSplit ? (
+            <>
+                <div class="sl-flex stack">
+                    <div class="sl-flex copy">
+                        {showTitle && <h1 id={PAGE_TITLE_ID} data-page-title set:html={title} />}
+                        {tagline && <div class="tagline" set:html={tagline} />}
+                    </div>
+                    {actions.length > 0 && (
+                        <div class="sl-flex actions">
+                            {actions.map(({ icon, link: href, text, variant }) => (
+                                <LinkButton href={href} variant={variant} icon={icon?.name || icon}>
+                                    {text}
+                                </LinkButton>
+                            ))}
+                        </div>
+                    )}
+                </div>
+                <div class="hero-image-container">
+                    {darkImage && (
+                        <Image
+                            src={darkImage}
+                            {...imageAttrs}
+                            class:list={["hero-image", { "light:sl-hidden": Boolean(lightImage) }]}
+                        />
+                    )}
+                    {lightImage && <Image src={lightImage} {...imageAttrs} class="hero-image dark:sl-hidden" />}
+                    {rawHtml && <div class="hero-html sl-flex" set:html={rawHtml} />}
+                </div>
+            </>
+        ) : (
+            <div class="sl-flex stack">
+                {hasImage && (
+                    <div class="hero-image-centered">
+                        {darkImage && (
+                            <Image
+                                src={darkImage}
+                                {...imageAttrs}
+                                class:list={["hero-image", { "light:sl-hidden": Boolean(lightImage) }]}
+                            />
+                        )}
+                        {lightImage && <Image src={lightImage} {...imageAttrs} class="hero-image dark:sl-hidden" />}
+                        {rawHtml && <div class="hero-html sl-flex" set:html={rawHtml} />}
+                    </div>
+                )}
+                <div class="sl-flex copy">
+                    <h1 id={PAGE_TITLE_ID} data-page-title set:html={title} />
+                    {tagline && <div class="tagline" set:html={tagline} />}
+                </div>
+                {actions.length > 0 && (
+                    <div class="sl-flex actions">
+                        {actions.map(({ icon, link: href, text, variant }) => (
+                            <LinkButton href={href} variant={variant} icon={icon?.name || icon}>
+                                {text}
+                            </LinkButton>
+                        ))}
+                    </div>
+                )}
+            </div>
+        )
+    }
+</div>
+
+<style>
+    /* ---- Base / Centered layout ---- */
+    .hero {
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        padding-block: clamp(2rem, calc(1rem + 10vmin), 8rem);
+    }
+
+    .stack {
+        flex-direction: column;
+        gap: clamp(1.5rem, calc(1.5rem + 1vw), 2.5rem);
+        text-align: center;
+        align-items: center;
+    }
+
+    .copy {
+        flex-direction: column;
+        gap: 1rem;
+        align-items: center;
+    }
+
+    .copy > * {
+        max-width: 50ch;
+    }
+
+    h1 {
+        font-size: clamp(var(--sl-text-3xl), calc(0.25rem + 5vw), var(--sl-text-6xl));
+        line-height: var(--sl-line-height-headings);
+        font-weight: 600;
+        color: var(--nu-purple-100);
+    }
+
+    :root:not([data-theme="light"]) h1 {
+        color: var(--sl-color-white);
+    }
+
+    .tagline {
+        font-size: clamp(var(--sl-text-base), calc(0.0625rem + 1.5vw), var(--sl-text-lg));
+        color: var(--sl-color-gray-2);
+        max-width: 90vw;
+    }
+
+    .actions {
+        gap: 1rem;
+        flex-direction: column;
+        align-items: stretch;
+        width: 100%;
+        max-width: 300px;
+    }
+
+    .actions :global(a) {
+        width: auto;
+        justify-content: center;
+    }
+
+    .hero-image-centered {
+        display: flex;
+        align-items: center;
+        justify-content: center;
+    }
+
+    .hero-image-centered .hero-image,
+    .hero-image-centered .hero-html {
+        object-fit: contain;
+        width: min(90%, 500px);
+        height: auto;
+    }
+
+    @media (min-width: 50rem) {
+        .hero:not(.hero--split) .tagline {
+            white-space: nowrap;
+            max-width: none;
+        }
+
+        .actions {
+            flex-direction: row;
+            align-items: center;
+            width: auto;
+            max-width: none;
+        }
+
+        .actions :global(a) {
+            width: auto;
+        }
+    }
+
+    /* ---- Split layout ---- */
+    .hero--split {
+        display: grid;
+        grid-template-columns: 1fr;
+        gap: 2rem;
+        padding-block: clamp(2rem, calc(1rem + 8vmin), 6rem);
+    }
+
+    .hero--split .stack {
+        text-align: center;
+        align-items: center;
+        order: 2;
+    }
+
+    .hero--split .copy {
+        align-items: center;
+    }
+
+    .hero-image-container {
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        order: 1;
+    }
+
+    .hero-image-container .hero-image,
+    .hero-image-container .hero-html {
+        object-fit: contain;
+        width: min(60%, 240px);
+        height: auto;
+    }
+
+    @media (min-width: 50rem) {
+        .hero--split {
+            grid-template-columns: 3fr 2fr;
+            gap: 3rem;
+            align-items: center;
+        }
+
+        .hero--split .stack {
+            text-align: start;
+            align-items: flex-start;
+            order: unset;
+        }
+
+        .hero-image-container {
+            order: unset;
+            padding: 2rem;
+        }
+
+        .hero--split .copy {
+            align-items: flex-start;
+        }
+
+        .hero--split .actions {
+            justify-content: flex-start;
+        }
+
+        .hero-image-container .hero-image,
+        .hero-image-container .hero-html {
+            width: 100%;
+            max-width: 280px;
+        }
+    }
+</style>

package/src/components/ThemeToggle.astro

@@ -0,0 +1,199 @@
+---
+import crypto from "node:crypto";
+
+const id = `northwestern-theme-mask-${crypto.randomBytes(4).toString("hex")}`;
+const accessibleLabel = Astro.locals.t("themeSelect.accessibleLabel");
+---
+
+<northwestern-theme-toggle>
+    <button aria-label={accessibleLabel} aria-live="polite" title={accessibleLabel} type="button">
+        <svg aria-hidden="true" height="16" viewBox="0 0 24 24" width="16">
+            <mask class="moon" id={id}>
+                <rect fill="white" height="100%" width="100%" x="0" y="0"></rect>
+                <circle cx="24" cy="10" fill="black" r="6"></circle>
+            </mask>
+            <circle class="sun" cx="12" cy="12" mask={`url(#${id})`} r="6"></circle>
+            <g class="sun-beams" stroke="currentColor">
+                <line x1="12" x2="12" y1="1" y2="3"></line>
+                <line x1="12" x2="12" y1="21" y2="23"></line>
+                <line x1="4.22" x2="5.64" y1="4.22" y2="5.64"></line>
+                <line x1="18.36" x2="19.78" y1="18.36" y2="19.78"></line>
+                <line x1="1" x2="3" y1="12" y2="12"></line>
+                <line x1="21" x2="23" y1="12" y2="12"></line>
+                <line x1="4.22" x2="5.64" y1="19.78" y2="18.36"></line>
+                <line x1="18.36" x2="19.78" y1="5.64" y2="4.22"></line>
+            </g>
+        </svg>
+    </button>
+</northwestern-theme-toggle>
+
+<script is:inline>
+    StarlightThemeProvider.updatePickers();
+</script>
+
+<script>
+    type Theme = "auto" | "dark" | "light";
+
+    const storageKey = "starlight-theme";
+
+    function parseTheme(theme: unknown): Theme {
+        return theme === "auto" || theme === "dark" || theme === "light" ? theme : "auto";
+    }
+
+    function loadTheme(): Theme {
+        return parseTheme(typeof localStorage !== "undefined" && localStorage.getItem(storageKey));
+    }
+
+    function storeTheme(theme: Theme): void {
+        if (typeof localStorage !== "undefined") {
+            localStorage.setItem(storageKey, theme === "light" || theme === "dark" ? theme : "");
+        }
+    }
+
+    function getPreferredColorScheme(): Theme {
+        return matchMedia("(prefers-color-scheme: light)").matches ? "light" : "dark";
+    }
+
+    function onThemeChange(theme: Theme): void {
+        StarlightThemeProvider.updatePickers(theme);
+        document.documentElement.dataset.theme = theme === "auto" ? getPreferredColorScheme() : theme;
+        storeTheme(theme);
+        syncToggleButtons();
+    }
+
+    function syncToggleButtons(): void {
+        const currentTheme = parseTheme(document.documentElement.dataset.theme);
+        const nextTheme = currentTheme === "dark" ? "light" : "dark";
+
+        document.querySelectorAll("northwestern-theme-toggle button").forEach((button) => {
+            if (button instanceof HTMLButtonElement) {
+                button.setAttribute("aria-label", `${button.title}: ${nextTheme}`);
+                button.setAttribute("aria-pressed", String(currentTheme === "dark"));
+            }
+        });
+    }
+
+    matchMedia("(prefers-color-scheme: light)").addEventListener("change", () => {
+        if (loadTheme() === "auto") onThemeChange("auto");
+    });
+
+    class NorthwesternThemeToggle extends HTMLElement {
+        constructor() {
+            super();
+            onThemeChange(loadTheme());
+
+            this.querySelector("button")?.addEventListener("click", () => {
+                const theme = parseTheme(document.documentElement.dataset.theme);
+                const newTheme = theme === "dark" ? "light" : "dark";
+                onThemeChange(newTheme);
+            });
+        }
+    }
+
+    if (!customElements.get("northwestern-theme-toggle")) {
+        customElements.define("northwestern-theme-toggle", NorthwesternThemeToggle);
+    }
+</script>
+
+<style>
+    @layer northwestern {
+        northwestern-theme-toggle {
+            --nu-theme-toggle-duration: 400ms;
+            --nu-theme-toggle-ease: cubic-bezier(0.5, 1.25, 0.75, 1.25);
+            align-self: stretch;
+            display: inline-flex;
+        }
+
+        northwestern-theme-toggle button {
+            display: inline-flex;
+            align-items: center;
+            justify-content: center;
+            min-width: auto;
+            height: 100%;
+            padding: 0.5rem;
+            background-color: transparent;
+            border: 1px solid currentcolor;
+            color: inherit;
+            cursor: pointer;
+        }
+
+        northwestern-theme-toggle svg {
+            stroke-linecap: round;
+        }
+
+        northwestern-theme-toggle svg :is(.moon, .sun, .sun-beams) {
+            transform-origin: center;
+        }
+
+        northwestern-theme-toggle svg :is(.moon, .sun) {
+            fill: currentcolor;
+        }
+
+        northwestern-theme-toggle svg .sun-beams {
+            stroke: currentcolor;
+            stroke-width: 2px;
+        }
+
+        northwestern-theme-toggle button:focus-visible {
+            outline: 2px solid var(--nu-focus-ring);
+            outline-offset: 2px;
+        }
+
+        :global([data-theme="dark"]) northwestern-theme-toggle svg .sun {
+            transform: scale(1.75);
+        }
+
+        :global([data-theme="dark"]) northwestern-theme-toggle svg .sun-beams {
+            opacity: 0;
+        }
+
+        :global([data-theme="dark"]) northwestern-theme-toggle svg .moon circle {
+            transform: translateX(-7px);
+        }
+
+        @supports (cx: 1) {
+            :global([data-theme="dark"]) northwestern-theme-toggle svg .moon circle {
+                cx: 17;
+                transform: translateX(0);
+            }
+        }
+
+        @media (prefers-reduced-motion: no-preference) {
+            northwestern-theme-toggle svg .sun {
+                transition: transform var(--nu-theme-toggle-duration) var(--nu-theme-toggle-ease);
+            }
+
+            northwestern-theme-toggle svg .sun-beams {
+                transition:
+                    opacity var(--nu-theme-toggle-duration) ease,
+                    transform var(--nu-theme-toggle-duration) var(--nu-theme-toggle-ease);
+            }
+
+            northwestern-theme-toggle svg .moon circle {
+                transition: transform calc(var(--nu-theme-toggle-duration) / 2) ease-out;
+            }
+
+            @supports (cx: 1) {
+                northwestern-theme-toggle svg .moon circle {
+                    transition: cx calc(var(--nu-theme-toggle-duration) / 2) ease-out;
+                }
+            }
+
+            :global([data-theme="dark"]) northwestern-theme-toggle svg .sun {
+                transform: scale(1.75);
+                transition-duration: calc(var(--nu-theme-toggle-duration) / 2);
+                transition-timing-function: ease;
+            }
+
+            :global([data-theme="dark"]) northwestern-theme-toggle svg .sun-beams {
+                transform: rotateZ(-25deg);
+                transition-duration: calc(var(--nu-theme-toggle-duration) / 4);
+            }
+
+            :global([data-theme="dark"]) northwestern-theme-toggle svg .moon circle {
+                transition-delay: calc(var(--nu-theme-toggle-duration) / 4);
+                transition-duration: var(--nu-theme-toggle-duration);
+            }
+        }
+    }
+</style>