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

package/src/components/Hero.astro

@@ -101,7 +101,6 @@ const imageWidth = themeConfig.homepage.imageWidth;
 </div>
 
 <style>
-    /* ---- Base / Centered layout ---- */
     .hero {
         display: flex;
         align-items: center;
@@ -187,7 +186,6 @@ const imageWidth = themeConfig.homepage.imageWidth;
         }
     }
 
-    /* ---- Split layout ---- */
     .hero--split {
         display: grid;
         grid-template-columns: 1fr;

package/src/components/Kbd.astro

@@ -0,0 +1,147 @@
+---
+import "../styles/components/kbd.css";
+import Tooltip from "./Tooltip.astro";
+
+interface Props {
+    /** Explicit array of key names. Overrides children parsing. */
+    keys?: string[];
+    /** Tooltip description shown on hover. Wraps the Kbd in a Tooltip when set. */
+    tip?: string;
+}
+
+/** Map semantic key names to display symbols (Mac). */
+const KEY_SYMBOLS_MAC: Record<string, string> = {
+    mod: "⌘",
+    command: "⌘",
+    cmd: "⌘",
+    meta: "⌘",
+    control: "⌃",
+    ctrl: "⌃",
+    option: "⌥",
+    alt: "⌥",
+    shift: "⇧",
+    enter: "↵",
+    return: "↵",
+    backspace: "⌫",
+    delete: "⌦",
+    escape: "Esc",
+    esc: "Esc",
+    tab: "⇥",
+    capslock: "⇪",
+    space: "␣",
+    up: "↑",
+    down: "↓",
+    left: "←",
+    right: "→",
+    pageup: "⇞",
+    pagedown: "⇟",
+    home: "↖",
+    end: "↘",
+};
+
+/** Map semantic key names to display symbols (Windows/Linux). */
+const KEY_SYMBOLS_OTHER: Record<string, string> = {
+    ...KEY_SYMBOLS_MAC,
+    mod: "Ctrl",
+    command: "Ctrl",
+    cmd: "Ctrl",
+    meta: "Win",
+    control: "Ctrl",
+    ctrl: "Ctrl",
+    option: "Alt",
+    alt: "Alt",
+};
+
+/** Keys that differ between platforms. */
+const PLATFORM_KEYS = new Set(["mod", "command", "cmd", "meta", "control", "ctrl", "option", "alt"]);
+
+/** Canonical modifier ordering: Ctrl, Meta/Cmd, Alt/Option, Shift, then others. */
+const MODIFIER_ORDER_MAC = ["⌃", "⌘", "⌥", "⇧"];
+const MODIFIER_ORDER_OTHER = ["Ctrl", "Win", "Alt", "Shift"];
+
+function resolveKeys(rawKeys: string[], symbols: Record<string, string>): string[] {
+    return rawKeys.map((k) => {
+        const lower = k.trim().toLowerCase();
+        return symbols[lower] ?? k.trim();
+    });
+}
+
+function sortKeys(keys: string[], order: string[]): string[] {
+    return [...keys].sort((a, b) => {
+        const ai = order.indexOf(a);
+        const bi = order.indexOf(b);
+        if (ai !== -1 && bi !== -1) return ai - bi;
+        if (ai !== -1) return -1;
+        if (bi !== -1) return 1;
+        return 0;
+    });
+}
+
+const { keys: keysProp, tip: kbdTip } = Astro.props;
+
+let rawSlot = "";
+if (!keysProp && Astro.slots.has("default")) {
+    rawSlot = await Astro.slots.render("default").then((s) => s.replace(/<[^>]*>/g, "").trim());
+}
+
+const rawKeys =
+    keysProp ??
+    rawSlot
+        .split("+")
+        .map((s) => s.trim())
+        .filter(Boolean);
+const hasPlatformKeys = rawKeys.some((k) => PLATFORM_KEYS.has(k.toLowerCase()));
+
+const macKeys = sortKeys(resolveKeys(rawKeys, KEY_SYMBOLS_MAC), MODIFIER_ORDER_MAC);
+const otherKeys = sortKeys(resolveKeys(rawKeys, KEY_SYMBOLS_OTHER), MODIFIER_ORDER_OTHER);
+
+const ariaLabel = rawKeys.join(" + ");
+---
+
+{() => {
+    const kbdElement = (
+        <kbd class="nu-kbd" aria-label={ariaLabel}>
+            {hasPlatformKeys ? (
+                <>
+                    <span class="nu-kbd__mac">
+                        {macKeys.map((key, i) => (
+                            <>
+                                {i > 0 && <span class="nu-kbd__sep" aria-hidden="true">+</span>}
+                                <kbd class="nu-kbd__key">{key}</kbd>
+                            </>
+                        ))}
+                    </span>
+                    <span class="nu-kbd__other">
+                        {otherKeys.map((key, i) => (
+                            <>
+                                {i > 0 && <span class="nu-kbd__sep" aria-hidden="true">+</span>}
+                                <kbd class="nu-kbd__key">{key}</kbd>
+                            </>
+                        ))}
+                    </span>
+                </>
+            ) : (
+                macKeys.map((key, i) => (
+                    <>
+                        {i > 0 && <span class="nu-kbd__sep" aria-hidden="true">+</span>}
+                        <kbd class="nu-kbd__key">{key}</kbd>
+                    </>
+                ))
+            )}
+        </kbd>
+    );
+
+    return kbdTip
+        ? <Tooltip tip={kbdTip} underline={false}>{kbdElement}</Tooltip>
+        : kbdElement;
+}}
+
+<script>
+    function detectPlatform() {
+        const isMac = navigator.userAgentData
+            ? navigator.userAgentData.platform === "macOS"
+            : /Mac|iPhone|iPad|iPod/.test(navigator.userAgent);
+        document.documentElement.setAttribute("data-platform", isMac ? "mac" : "other");
+    }
+    detectPlatform();
+</script>

package/src/components/Property.astro

@@ -0,0 +1,64 @@
+---
+interface Props {
+    /** Property name (displayed in monospace). */
+    name: string;
+    /** Type annotation (displayed in monospace, supports union syntax). */
+    type?: string;
+    /** URL to link the type annotation to (e.g. a type definition or external docs). */
+    typeHref?: string;
+    /** Default value (displayed in monospace). */
+    default?: string;
+    /** Mark as required. Displays a "Required" badge. */
+    required?: boolean;
+    /** Mark as deprecated. Strikes through the name and mutes the row. */
+    deprecated?: boolean;
+    /** Version this property was added in. Displays a small badge. */
+    since?: string;
+}
+
+if (!globalThis.__nuPropertySlugs) {
+    globalThis.__nuPropertySlugs = { page: "", counts: new Map<string, number>() };
+}
+const pageSlugState = globalThis.__nuPropertySlugs;
+const currentPage = Astro.url.pathname;
+if (pageSlugState.page !== currentPage) {
+    pageSlugState.page = currentPage;
+    pageSlugState.counts.clear();
+}
+
+const { name, type, typeHref, default: defaultValue, required, deprecated, since } = Astro.props;
+const hasInlineBadges = required || since || deprecated;
+const rawSlug = name
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-|-$/g, "");
+const baseSlug = `prop-${rawSlug || "key"}`;
+const count = (pageSlugState.counts.get(baseSlug) ?? 0) + 1;
+pageSlugState.counts.set(baseSlug, count);
+const slug = count === 1 ? baseSlug : `${baseSlug}-${count}`;
+---
+
+<div class:list={["nu-property", { "nu-property--required": required, "nu-property--deprecated": deprecated }]} role="listitem" id={slug}>
+    <div class="nu-property__head">
+        <span class="nu-property__prop-col">
+            <a class="nu-property__anchor" href={`#${slug}`} aria-label={`Link to ${name}`}>#</a><code class="nu-property__name">{name}</code>
+            {hasInlineBadges && (
+                <span class="nu-property__badges">
+                    {required && <span class="nu-property__badge nu-property__badge--required" aria-label="required">Required</span>}
+                    {since && <span class="nu-property__badge nu-property__badge--since">v{since}</span>}
+                    {deprecated && <span class="nu-property__badge nu-property__badge--deprecated" aria-label="deprecated">Deprecated</span>}
+                </span>
+            )}
+        </span>
+        {type && typeHref
+            ? <a class="nu-property__type-link" href={typeHref}><code class="nu-property__type">{type}</code></a>
+            : type && <code class="nu-property__type">{type}</code>
+        }
+        <span class="nu-property__default-col">
+            {defaultValue && <span class="nu-property__badge nu-property__badge--default"><code>{defaultValue}</code></span>}
+        </span>
+    </div>
+    <div class="nu-property__description">
+        <slot />
+    </div>
+</div>

package/src/components/PropertyGroup.astro

@@ -0,0 +1,13 @@
+---
+interface Props {
+    /** Group heading text. */
+    title: string;
+}
+
+const { title } = Astro.props;
+---
+
+<div class="nu-property-group">
+    <div class="nu-property-group__title">{title}</div>
+    <slot />
+</div>

package/src/components/PropertyTable.astro

@@ -0,0 +1,54 @@
+---
+import "../styles/components/property-table.css";
+
+type ColumnShorthand = "name" | "type" | "default";
+type ColumnConfig = { key: ColumnShorthand; label: string };
+type ColumnDef = ColumnShorthand | ColumnConfig;
+
+interface Props {
+    /** Optional heading above the table. */
+    title?: string;
+    /** Layout variant. "list" (default) shows stacked rows. "table" shows a columnar grid. */
+    variant?: "list" | "table";
+    /** Columns to display in table variant. Array of field keys or { key, label } objects. */
+    columns?: ColumnDef[];
+    /** Show "Optional" label on non-required properties. */
+    showOptional?: boolean;
+}
+
+const DEFAULT_LABELS: Record<ColumnShorthand, string> = {
+    name: "Prop",
+    type: "Type",
+    default: "Default",
+};
+
+const { title, variant = "list", columns: columnsProp, showOptional = false } = Astro.props;
+const isTable = variant === "table";
+
+const resolvedColumns = isTable
+    ? (columnsProp ?? ["name", "type", "default"]).map((col) =>
+          typeof col === "string" ? { key: col, label: DEFAULT_LABELS[col] } : col,
+      )
+    : [];
+
+const columnCount = resolvedColumns.length;
+const columnKeys = resolvedColumns.map((c) => c.key);
+---
+
+<div
+    class:list={["nu-property-table", { "nu-property-table--table": isTable, "nu-property-table--show-optional": showOptional }]}
+    style={isTable ? `--nu-pt-columns: ${columnCount};` : undefined}
+    data-columns={isTable ? columnKeys.join(",") : undefined}
+>
+    {title && <div class="nu-property-table__header">{title}</div>}
+    {isTable && (
+        <div class="nu-property-table__columns" aria-hidden="true">
+            {resolvedColumns.map((col) => (
+                <span>{col.label}</span>
+            ))}
+        </div>
+    )}
+    <div class="nu-property-table__body not-content" role="list">
+        <slot />
+    </div>
+</div>

package/src/components/Term.astro

@@ -0,0 +1,29 @@
+---
+import { getTerm } from "./glossary-store.ts";
+import Tooltip from "./Tooltip.astro";
+
+interface Props {
+    /** Key matching a Glossary entry. */
+    of: string;
+    /** Preferred position. */
+    side?: "top" | "bottom";
+    /** Render with a dotted underline indicator. */
+    underline?: boolean;
+    /** Semantic color variant. */
+    variant?: "note" | "tip" | "caution" | "danger";
+    /** Custom background color. */
+    color?: string;
+}
+
+const { of: key, side, underline, variant, color } = Astro.props;
+const tip = getTerm(key);
+const hasSlot = Astro.slots.has("default");
+
+if (!tip) {
+    throw new Error(`[Term] No glossary entry found for "${key}". Add it to a <Glossary> component above this <Term>.`);
+}
+---
+
+<Tooltip tip={tip} side={side} underline={underline} variant={variant} color={color}>
+    {hasSlot ? <slot /> : key}
+</Tooltip>

package/src/components/Tooltip.astro

@@ -0,0 +1,138 @@
+---
+import { darken, isDark, lighten, toHex } from "khroma";
+import "../styles/components/tooltip.css";
+
+type TooltipVariant = "note" | "tip" | "caution" | "danger";
+
+interface Props {
+    /** Definition text shown in the tooltip. Ignored when the content slot is used. */
+    tip?: string;
+    /** Preferred position. */
+    side?: "top" | "bottom";
+    /** Render the trigger with a dotted underline indicator. */
+    underline?: boolean;
+    /** Semantic variant matching Aside types. Sets background, text, and border colors. */
+    variant?: TooltipVariant;
+    /** Custom background color. Overrides variant. Text color is auto-computed for WCAG contrast. */
+    color?: string;
+}
+
+/** Maps to --nu-color-* tokens in variables.css */
+const VARIANT_COLORS: Record<TooltipVariant, string> = {
+    note: "#5091cd", // --nu-color-info
+    tip: "#008656", // --nu-color-success
+    caution: "#ffc520", // --nu-color-warning
+    danger: "#ef553f", // --nu-color-danger
+};
+
+const { tip, side = "top", underline = true, variant, color } = Astro.props;
+const id = `nu-tip-${Math.random().toString(36).slice(2, 9)}`;
+
+const hasTipSlot = Astro.slots.has("tip");
+
+const resolvedColor = color ?? (variant ? VARIANT_COLORS[variant] : undefined);
+
+let colorStyles: string | undefined;
+if (resolvedColor) {
+    const bg = toHex(resolvedColor);
+    const textColor = isDark(bg) ? "#fff" : "#1a1a1a";
+    const borderColor = isDark(bg) ? toHex(lighten(bg, 12)) : toHex(darken(bg, 12));
+    colorStyles = `--nu-tip-bg: ${bg}; --nu-tip-text: ${textColor}; --nu-tip-border: ${borderColor}; --nu-tip-arrow: ${bg};`;
+}
+---
+
+<span
+    class:list={["nu-tooltip", `nu-tooltip--${side}`, { "nu-tooltip--underline": underline, "nu-tooltip--custom": !!resolvedColor }]}
+    data-tooltip-id={id}
+    style={colorStyles}
+>
+    <span class="nu-tooltip__trigger" tabindex="0" aria-describedby={id}><slot /></span>
+    <span class="nu-tooltip__content" role="tooltip" id={id} popover="manual">
+        {hasTipSlot ? <slot name="tip" /> : tip}
+        <span class="nu-tooltip__arrow"></span>
+    </span>
+</span>
+
+<script>
+    const initialized = new WeakSet<HTMLElement>();
+
+    function initTooltips() {
+        document.querySelectorAll<HTMLElement>(".nu-tooltip").forEach((wrapper) => {
+            if (initialized.has(wrapper)) return;
+            initialized.add(wrapper);
+
+            const trigger = wrapper.querySelector<HTMLElement>(".nu-tooltip__trigger");
+            const content = wrapper.querySelector<HTMLElement>(".nu-tooltip__content");
+            if (!trigger || !content) return;
+
+            let isVisible = false;
+            const hasPopover = "showPopover" in content;
+
+            function onScroll() {
+                if (isVisible) position();
+            }
+
+            function show() {
+                if (isVisible) return;
+                isVisible = true;
+                if (hasPopover) {
+                    content!.showPopover();
+                } else {
+                    content!.style.position = "fixed";
+                    content!.style.opacity = "1";
+                    content!.style.visibility = "visible";
+                    content!.style.pointerEvents = "auto";
+                }
+                position();
+                window.addEventListener("scroll", onScroll, { passive: true });
+            }
+
+            function hide() {
+                if (!isVisible) return;
+                isVisible = false;
+                if (hasPopover) {
+                    content!.hidePopover();
+                } else {
+                    content!.style.opacity = "0";
+                    content!.style.visibility = "hidden";
+                    content!.style.pointerEvents = "none";
+                }
+                window.removeEventListener("scroll", onScroll);
+            }
+
+            function position() {
+                const rect = trigger!.getBoundingClientRect();
+                const side = wrapper.classList.contains("nu-tooltip--bottom") ? "bottom" : "top";
+                const gap = 8;
+
+                content!.style.left = `${rect.left + rect.width / 2}px`;
+
+                if (side === "top") {
+                    content!.style.top = `${rect.top - gap}px`;
+                    content!.style.transform = "translate(-50%, -100%)";
+                } else {
+                    content!.style.top = `${rect.bottom + gap}px`;
+                    content!.style.transform = "translate(-50%, 0)";
+                }
+            }
+
+            wrapper.addEventListener("mouseenter", show);
+            wrapper.addEventListener("mouseleave", hide);
+            trigger.addEventListener("focus", show);
+            trigger.addEventListener("blur", hide);
+
+            content.addEventListener("mouseenter", () => { isVisible = true; });
+            content.addEventListener("mouseleave", hide);
+        });
+
+    }
+
+    document.addEventListener("keydown", (e) => {
+        if (e.key === "Escape") {
+            (document.activeElement as HTMLElement)?.blur();
+        }
+    });
+
+    initTooltips();
+    document.addEventListener("astro:after-swap", initTooltips);
+</script>

package/src/components/glossary-store.ts

@@ -0,0 +1,12 @@
+/** Module-level glossary store. Populated by `<Glossary/>`, read by Term during the same Astro build pass. */
+const terms = new Map<string, string>();
+
+export function setTerms(entries: Record<string, string>): void {
+    for (const [key, value] of Object.entries(entries)) {
+        terms.set(key, value);
+    }
+}
+
+export function getTerm(key: string): string | undefined {
+    return terms.get(key);
+}

package/src/components/index.ts

@@ -0,0 +1,8 @@
+export { default as Expandable } from "./Expandable.astro";
+export { default as Glossary } from "./Glossary.astro";
+export { default as Kbd } from "./Kbd.astro";
+export { default as Property } from "./Property.astro";
+export { default as PropertyGroup } from "./PropertyGroup.astro";
+export { default as PropertyTable } from "./PropertyTable.astro";
+export { default as Term } from "./Term.astro";
+export { default as Tooltip } from "./Tooltip.astro";

package/src/rehype-table-scroll.ts

@@ -0,0 +1,35 @@
+/**
+ * Rehype plugin that wraps `<table>` elements in a scrollable container at build time.
+ *
+ * Inserts a `<div class="nu-table-scroll">` around each table with `tabindex="0"`,
+ * `role="region"`, and `aria-label` for keyboard scrollability. Runs during the
+ * Astro build so the HTML arrives with the wrapper already in place.
+ */
+import type { Element, Nodes, Root } from "hast";
+
+function walk(node: Nodes) {
+    if (!("children" in node)) return;
+    for (let i = 0; i < node.children.length; i++) {
+        const child = node.children[i];
+        if (child.type === "element" && (child as Element).tagName === "table") {
+            const wrapper: Element = {
+                type: "element",
+                tagName: "div",
+                properties: {
+                    className: ["nu-table-scroll"],
+                    tabindex: 0,
+                    role: "region",
+                    ariaLabel: "Scrollable table",
+                },
+                children: [child as Element],
+            };
+            node.children[i] = wrapper;
+        } else {
+            walk(child as Nodes);
+        }
+    }
+}
+
+export default function rehypeTableScroll() {
+    return (tree: Root) => walk(tree);
+}

package/src/scripts/mermaid/focus.ts

@@ -0,0 +1,100 @@
+/**
+ * Focus management and keyboard shortcut handler for the fullscreen overlay.
+ *
+ * Implements WCAG-compliant focus trapping (Tab/Shift+Tab cycle within the dialog),
+ * zoom/pan keyboard shortcuts, and modality-aware initial focus placement.
+ */
+
+import type { PanZoomController } from "./pan-zoom";
+
+/** Configuration for {@link installKeyboardAndFocus}. */
+export interface KeyboardFocusConfig {
+    /** The dialog overlay element (focus trap boundary). */
+    overlay: HTMLElement;
+    /** The controls bar containing focusable buttons. */
+    controls: HTMLElement;
+    /** Pan/zoom controller for keyboard zoom and arrow-key panning. */
+    panZoom: PanZoomController;
+    /** Callback to close the overlay (triggered by Escape). */
+    onClose: () => void;
+    /** Whether the overlay was opened via keyboard (Enter/Space on the trigger button). */
+    openedViaKeyboard: boolean;
+}
+
+const FOCUSABLE_SELECTOR = 'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])';
+const KEYBOARD_ZOOM_FACTOR = 1.2;
+const ARROW_PAN_DISTANCE = 50;
+
+/** Map of keyboard shortcuts to their handler functions. */
+type ShortcutHandler = (pz: PanZoomController, close: () => void) => void;
+
+const KEYBOARD_SHORTCUTS: Record<string, ShortcutHandler> = {
+    Escape: (_pz, close) => close(),
+    "+": (pz) => pz.zoomTo(pz.scale * KEYBOARD_ZOOM_FACTOR),
+    "=": (pz) => pz.zoomTo(pz.scale * KEYBOARD_ZOOM_FACTOR),
+    "-": (pz) => pz.zoomTo(pz.scale / KEYBOARD_ZOOM_FACTOR),
+    _: (pz) => pz.zoomTo(pz.scale / KEYBOARD_ZOOM_FACTOR),
+    "0": (pz) => pz.resetView(),
+    ArrowUp: (pz) => pz.panBy(0, ARROW_PAN_DISTANCE),
+    ArrowDown: (pz) => pz.panBy(0, -ARROW_PAN_DISTANCE),
+    ArrowLeft: (pz) => pz.panBy(ARROW_PAN_DISTANCE, 0),
+    ArrowRight: (pz) => pz.panBy(-ARROW_PAN_DISTANCE, 0),
+};
+
+/**
+ * Install keyboard event handlers and set initial focus.
+ *
+ * Focus placement depends on how the overlay was opened:
+ * - **Keyboard** (Enter/Space): focuses the first control button with a visible focus ring.
+ * - **Mouse** (click): focuses the overlay container itself (invisible, but allows Tab to work).
+ *
+ * @returns A cleanup function that removes all installed listeners.
+ */
+export function installKeyboardAndFocus({
+    overlay,
+    controls,
+    panZoom,
+    onClose,
+    openedViaKeyboard,
+}: KeyboardFocusConfig): () => void {
+    function handleKeydown(event: KeyboardEvent): void {
+        if (event.key === "Tab") {
+            trapFocus(overlay, event);
+            return;
+        }
+
+        const handler = KEYBOARD_SHORTCUTS[event.key];
+        if (handler) {
+            handler(panZoom, onClose);
+            event.preventDefault();
+        }
+    }
+
+    window.addEventListener("keydown", handleKeydown);
+
+    if (openedViaKeyboard) {
+        controls.querySelector<HTMLElement>(".nu-mermaid-btn")?.focus();
+    } else {
+        overlay.setAttribute("tabindex", "-1");
+        overlay.focus();
+    }
+
+    return () => window.removeEventListener("keydown", handleKeydown);
+}
+
+/** Cycle Tab/Shift+Tab focus within the overlay boundary. */
+function trapFocus(boundary: HTMLElement, event: KeyboardEvent): void {
+    const focusableElements = boundary.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTOR);
+    if (!focusableElements.length) return;
+
+    const firstElement = focusableElements[0];
+    const lastElement = focusableElements[focusableElements.length - 1];
+
+    if (event.shiftKey && document.activeElement === firstElement) {
+        event.preventDefault();
+        lastElement.focus();
+    } else if (!event.shiftKey && document.activeElement === lastElement) {
+        event.preventDefault();
+        firstElement.focus();
+    }
+}