@dominikcz/greg 0.9.27

package/src/lib/MarkdownDocs/markdownRendererRuntime.ts

@@ -0,0 +1,314 @@
+import remarkParse from "remark-parse";
+import remarkGfm from "remark-gfm";
+import remarkRehype from "remark-rehype";
+import rehypeStringify from "rehype-stringify";
+import rehypeSlug from "rehype-slug";
+import rehypeAutolinkHeadings from "rehype-autolink-headings";
+
+import { rehypeTocPlaceholder } from "./rehypeToc.js";
+import { remarkContainers, rehypeContainers } from "./remarkContainers.js";
+import rehypeCodeGroup from "./rehypeCodeGroup.js";
+import rehypeCodeTitle from "./rehypeCodeTitle.js";
+import { remarkCodeMeta } from "./remarkCodeMeta.js";
+import { remarkCustomAnchors } from "./remarkCustomAnchors.js";
+import { remarkInlineAttrs } from "./remarkInlineAttrs.js";
+import { remarkImportsBrowser } from "./remarkImportsBrowser.js";
+
+import Badge from "../components/Badge.svelte";
+import Button from "../components/Button.svelte";
+import Image from "../components/Image.svelte";
+import Link from "../components/Link.svelte";
+import CodeGroup from "../components/CodeGroup.svelte";
+import Hero from "../components/Hero.svelte";
+import Features from "../components/Features.svelte";
+import TeamMembers from "../components/TeamMembers.svelte";
+
+export type PluginEntry = {
+    name: string;
+    plugin: any;
+    options?: Record<string, any>;
+};
+
+export type PropsBuilder = (el: HTMLElement) => Record<string, any>;
+
+export type ComponentHydrationEntry = {
+    component: any;
+    buildProps: PropsBuilder;
+    selector?: string;
+};
+
+export type RenderHandlerContext = {
+    mermaidThemeConfig: Record<string, unknown>;
+};
+
+export type RenderHandler = {
+    name: string;
+    run: (
+        root: HTMLElement,
+        context: RenderHandlerContext,
+    ) => void | Promise<void>;
+};
+
+const HEADER_AUTOLINK_OPTIONS = {
+    behavior: "prepend",
+    properties: {
+        class: "header-anchor",
+        ariaHidden: "true",
+        tabIndex: -1,
+    },
+    content: { type: "text", value: "#" },
+};
+
+export function buildPropsFromAttributes(
+    el: HTMLElement,
+): Record<string, string> {
+    const props: Record<string, string> = {};
+    for (const attr of Array.from(el.attributes)) {
+        props[attr.name] = attr.value;
+    }
+    // If Badge / Button has text children but no text prop, pass textContent.
+    if (!props.text && el.textContent?.trim()) {
+        props.text = el.textContent.trim();
+    }
+    return props;
+}
+
+export function parseCodeGroupProps(el: HTMLElement) {
+    const tabsRaw = el.getAttribute("data-codegroup-tabs") ?? "[]";
+    let tabs: string[] = [];
+    try {
+        const parsed = JSON.parse(tabsRaw);
+        if (Array.isArray(parsed)) {
+            tabs = parsed.map((value) => String(value));
+        }
+    } catch {
+        tabs = [];
+    }
+
+    const blocks = Array.from(el.querySelectorAll(":scope > .rcg-block")).map(
+        (block) => (block as HTMLElement).innerHTML,
+    );
+
+    if (!tabs.length) {
+        tabs = blocks.map((_value, index) => `Tab ${index + 1}`);
+    }
+
+    const initialActive = Number(el.getAttribute("data-codegroup-active") ?? "0");
+
+    return {
+        tabs,
+        blocks,
+        initialActive: Number.isFinite(initialActive) ? initialActive : 0,
+    };
+}
+
+function parseJsonAttribute<T>(
+    el: HTMLElement,
+    attribute: string,
+    fallback: T,
+): T {
+    const raw = el.getAttribute(attribute);
+    if (!raw) return fallback;
+    try {
+        return JSON.parse(raw) as T;
+    } catch {
+        return fallback;
+    }
+}
+
+function parseHeroProps(el: HTMLElement) {
+    const props = buildPropsFromAttributes(el);
+    const {
+        ["data-hydrate"]: _dataHydrate,
+        ["data-hero-image"]: _heroImage,
+        ["data-hero-actions"]: _heroActions,
+        ...plainProps
+    } = props;
+    const image = parseJsonAttribute(el, "data-hero-image", undefined);
+    const actions = parseJsonAttribute(el, "data-hero-actions", [] as any[]);
+    return {
+        ...plainProps,
+        ...(image ? { image } : {}),
+        actions,
+    };
+}
+
+function parseFeaturesProps(el: HTMLElement) {
+    const features = parseJsonAttribute(el, "data-features", [] as any[]);
+    return { features };
+}
+
+function parseTeamMembersProps(el: HTMLElement) {
+    const props = buildPropsFromAttributes(el);
+    const {
+        ["data-hydrate"]: _dataHydrate,
+        ["data-members"]: _members,
+        ["members"]: _membersLegacy,
+        ...plainProps
+    } = props;
+    const members = parseJsonAttribute(
+        el,
+        "data-members",
+        parseJsonAttribute(el, "members", [] as any[]),
+    );
+    return {
+        ...plainProps,
+        members,
+    };
+}
+
+export const COMPONENT_REGISTRY: Record<string, ComponentHydrationEntry> = {
+    badge: {
+        component: Badge,
+        buildProps: buildPropsFromAttributes,
+    },
+    button: {
+        component: Button,
+        buildProps: buildPropsFromAttributes,
+    },
+    image: {
+        component: Image,
+        buildProps: buildPropsFromAttributes,
+    },
+    link: {
+        component: Link,
+        buildProps: buildPropsFromAttributes,
+    },
+    codegroup: {
+        component: CodeGroup,
+        buildProps: parseCodeGroupProps,
+    },
+    hero: {
+        component: Hero,
+        buildProps: parseHeroProps,
+        selector: "hero, [data-hydrate=hero]",
+    },
+    features: {
+        component: Features,
+        buildProps: parseFeaturesProps,
+        selector: "features, [data-hydrate=features]",
+    },
+    teammembers: {
+        component: TeamMembers,
+        buildProps: parseTeamMembersProps,
+        selector: "teammembers, [data-hydrate=teammembers]",
+    },
+};
+
+export function getRuntimeRenderHandlers(deps: {
+    hydrateComponents: (root: HTMLElement) => void;
+    initMermaid: (
+        root: HTMLElement,
+        themeConfig: Record<string, unknown>,
+    ) => void | Promise<void>;
+}): RenderHandler[] {
+    return [
+        {
+            name: "hydrate-components",
+            run: (root) => deps.hydrateComponents(root),
+        },
+        {
+            name: "init-mermaid",
+            run: (root, context) =>
+                deps.initMermaid(root, context.mermaidThemeConfig),
+        },
+    ];
+}
+
+export function getThemeChangeRenderHandlers(deps: {
+    rerenderMermaid: (
+        root: HTMLElement,
+        themeConfig: Record<string, unknown>,
+    ) => void | Promise<void>;
+}): RenderHandler[] {
+    return [
+        {
+            name: "rerender-mermaid",
+            run: (root, context) =>
+                deps.rerenderMermaid(root, context.mermaidThemeConfig),
+        },
+    ];
+}
+
+export async function runRenderHandlers(
+    root: HTMLElement,
+    handlers: RenderHandler[],
+    context: RenderHandlerContext,
+) {
+    for (const handler of handlers) {
+        try {
+            await handler.run(root, context);
+        } catch {
+            // Individual handler failures should not block other handlers.
+            continue;
+        }
+    }
+}
+
+export function getRemarkPluginEntries(
+    currentBaseUrl: string,
+    currentDocsPrefix: string,
+): PluginEntry[] {
+    return [
+        { name: "remark-parse", plugin: remarkParse },
+        { name: "remark-gfm", plugin: remarkGfm },
+        { name: "remark-inline-attrs", plugin: remarkInlineAttrs },
+        {
+            name: "remark-imports-browser",
+            plugin: remarkImportsBrowser,
+            options: {
+                baseUrl: currentBaseUrl,
+                docsPrefix: currentDocsPrefix,
+            },
+        },
+        { name: "remark-code-meta", plugin: remarkCodeMeta },
+        { name: "remark-containers", plugin: remarkContainers },
+        {
+            name: "remark-custom-anchors",
+            plugin: remarkCustomAnchors,
+        },
+        {
+            name: "remark-rehype",
+            plugin: remarkRehype,
+            options: { allowDangerousHtml: true },
+        },
+    ];
+}
+
+export function getRehypePluginEntries(deps: {
+    rehypeStepsWrapper: any;
+    rehypeMermaid: any;
+    rehypeShiki: any;
+}): PluginEntry[] {
+    return [
+        { name: "rehype-slug", plugin: rehypeSlug },
+        {
+            name: "rehype-autolink-headings",
+            plugin: rehypeAutolinkHeadings,
+            options: HEADER_AUTOLINK_OPTIONS,
+        },
+        { name: "rehype-steps-wrapper", plugin: deps.rehypeStepsWrapper },
+        { name: "rehype-mermaid", plugin: deps.rehypeMermaid },
+        { name: "rehype-shiki", plugin: deps.rehypeShiki },
+        { name: "rehype-containers", plugin: rehypeContainers },
+        { name: "rehype-code-group", plugin: rehypeCodeGroup },
+        { name: "rehype-code-title", plugin: rehypeCodeTitle },
+        { name: "rehype-toc-placeholder", plugin: rehypeTocPlaceholder },
+        {
+            name: "rehype-stringify",
+            plugin: rehypeStringify,
+            options: { allowDangerousHtml: true },
+        },
+    ];
+}
+
+export function applyPluginEntries(processor: any, entries: PluginEntry[]) {
+    for (const entry of entries) {
+        if (entry.options) {
+            processor.use(entry.plugin, entry.options);
+            continue;
+        }
+        processor.use(entry.plugin);
+    }
+    return processor;
+}

package/src/lib/MarkdownDocs/mermaidThemes.js

@@ -0,0 +1,319 @@
+/**
+ * mermaidThemes.js
+ *
+ * Built-in Mermaid diagram theme definitions.
+ * Each entry maps to a `MermaidConfig` object accepted by `mermaid.initialize()`.
+ *
+ * Colours inside `themeCSS` use CSS custom-property tokens (--mmd-*)
+ * defined in greg.scss, so diagrams react to Greg's light/dark
+ * mode via the CSS cascade — no JS re-render required for colour changes.
+ *
+ * `themeVariables` are baked into the SVG at render-time.
+ * MarkdownRenderer swaps between `material` (light) and `material-dark`
+ * when `colorTheme` changes, triggering a full SVG re-render so that
+ * background and internal mermaid colour math are also correct.
+ *
+ * Material theme design inspired by https://github.com/gotoailab/modern_mermaid
+ */
+
+// ── Shared Material themeCSS ─────────────────────────────────────────────────
+// Used by both `material` (light) and `material-dark`.
+// All colour values are CSS variable references resolved at paint-time.
+
+const MATERIAL_CSS = `
+    /* ── Flowchart nodes ──────────────────────────────────── */
+    .node rect, .node circle, .node polygon {
+        fill:   var(--mmd-node-bg) !important;
+        stroke: none               !important;
+        rx: 4px !important; ry: 4px !important;
+        filter: var(--mmd-shadow-sm);
+    }
+    .node .label {
+        font-family: "Roboto","Noto Sans SC",-apple-system,sans-serif;
+        font-weight: 500;
+        fill: var(--mmd-text) !important;
+        font-size: 14px;
+    }
+    .edgePath .path {
+        stroke: var(--mmd-line) !important; stroke-width: 2px !important;
+        stroke-linecap: round;
+    }
+    .arrowheadPath { fill: var(--mmd-line) !important; stroke: var(--mmd-line) !important; }
+    .edgeLabel {
+        background-color: var(--mmd-node-bg) !important;
+        color: var(--mmd-text) !important;
+        font-family: "Roboto","Noto Sans SC",-apple-system,sans-serif;
+        font-weight: 500; font-size: 13px;
+    }
+
+    /* ── Sequence diagram ─────────────────────────────────── */
+    .actor rect, g.actor rect, rect.actor {
+        fill: var(--mmd-node-bg) !important; stroke: none !important;
+        rx: 4px !important; ry: 4px !important;
+        filter: var(--mmd-shadow-sm) !important;
+    }
+    .actor { fill: var(--mmd-node-bg) !important; stroke: none !important; }
+    g.actor { filter: var(--mmd-shadow-sm); }
+    .actor text {
+        fill: var(--mmd-text) !important;
+        font-family: "Roboto","Noto Sans SC",-apple-system,sans-serif; font-weight: 500;
+    }
+    .actor-line {
+        stroke: var(--mmd-actor-line) !important; stroke-width: 2px !important;
+        stroke-dasharray: 4 4 !important;
+    }
+    .activation0, .activation1, .activation2,
+    rect.activation0, rect.activation1, rect.activation2 {
+        fill: var(--mmd-node-bg) !important; stroke: none !important;
+        filter: var(--mmd-shadow-sm) !important;
+    }
+    .messageLine0, .messageLine1 {
+        stroke: var(--mmd-line) !important; stroke-width: 2px !important;
+    }
+    .messageText {
+        fill: var(--mmd-text) !important;
+        font-family: "Roboto","Noto Sans SC",-apple-system,sans-serif;
+        font-weight: 500; font-size: 13px;
+    }
+    #arrowhead path, .arrowheadPath {
+        fill: var(--mmd-line) !important; stroke: var(--mmd-line) !important;
+    }
+
+    /* Note boxes */
+    .note, rect.note, g.note rect {
+        fill: var(--mmd-node-bg) !important; stroke: none !important;
+        rx: 4px !important; ry: 4px !important;
+        filter: var(--mmd-shadow-md) !important;
+    }
+    .noteText, text.noteText {
+        fill: var(--mmd-text) !important;
+        font-family: "Roboto","Noto Sans SC",-apple-system,sans-serif; font-weight: 500;
+    }
+
+    /* Loop / Alt / Opt boxes */
+    .labelBox {
+        fill: var(--mmd-node-bg) !important; stroke: var(--mmd-border) !important;
+        stroke-width: 1px !important; rx: 4px !important; ry: 4px !important;
+    }
+    .labelText, .loopText, text.labelText, text.loopText {
+        fill: var(--mmd-text) !important;
+        font-family: "Roboto","Noto Sans SC",-apple-system,sans-serif; font-weight: 500;
+    }
+    .loopLine { stroke: var(--mmd-actor-line) !important; stroke-width: 2px !important; }
+
+    /* ── Cluster / Subgraph ───────────────────────────────── */
+    .cluster rect {
+        fill: var(--mmd-node-bg) !important; stroke: var(--mmd-border) !important;
+        stroke-width: 1px !important; rx: 8px !important; ry: 8px !important;
+        filter: var(--mmd-shadow-sm);
+    }
+    .cluster text {
+        fill: var(--mmd-text-sub) !important;
+        font-family: "Roboto","Noto Sans SC",-apple-system,sans-serif;
+        font-weight: 500; text-transform: uppercase; letter-spacing: 1px; font-size: 12px;
+    }
+
+    /* ── Class diagram ────────────────────────────────────── */
+    .classGroup rect, g.classGroup rect,
+    g[id*="classid"] rect, g[id^="classid"] rect,
+    svg[aria-roledescription="classDiagram"] g.classGroup rect {
+        fill: var(--mmd-node-bg) !important; stroke: none !important;
+        rx: 4px !important; ry: 4px !important;
+        filter: var(--mmd-shadow-sm) !important;
+    }
+    .classLabel .label, .classLabel text, .class-label text {
+        fill: var(--mmd-text) !important;
+        font-family: "Roboto","Noto Sans SC",-apple-system,sans-serif; font-weight: 500;
+    }
+    .relationshipLine, .relation { stroke: var(--mmd-line) !important; stroke-width: 2px !important; }
+    .divider { stroke: var(--mmd-border) !important; stroke-width: 1px !important; }
+
+    /* ── State diagram ────────────────────────────────────── */
+    g[id*="state-"] rect, g[id^="state-"] rect, g.stateGroup rect,
+    .statediagram-state rect, .statediagram-state .state-inner, g[class*="state"] rect,
+    svg[aria-roledescription="statediagram"] g rect:not(circle):not([id*="start"]):not([id*="end"]) {
+        fill: var(--mmd-node-bg) !important; stroke: none !important;
+        rx: 4px !important; ry: 4px !important;
+        filter: var(--mmd-shadow-sm) !important;
+    }
+    .start-state circle, .end-state circle, circle[id*="start"], circle[id*="end"] {
+        fill: var(--mmd-accent-1) !important; stroke: none !important;
+        filter: var(--mmd-shadow-acc1);
+    }
+    .statediagram-state circle { stroke: none !important; }
+    .stateLabel text, .statediagram-state text, .state-note text {
+        fill: var(--mmd-text) !important;
+        font-family: "Roboto","Noto Sans SC",-apple-system,sans-serif; font-weight: 500;
+    }
+    .transition, path.transition { stroke: var(--mmd-line) !important; stroke-width: 2px !important; }
+    g.stateGroup.statediagram-cluster rect {
+        fill: var(--mmd-node-bg) !important; stroke: var(--mmd-border) !important;
+        stroke-width: 1px !important; rx: 8px !important; ry: 8px !important;
+    }
+
+    /* ── ER diagram ───────────────────────────────────────── */
+    .er.entityBox, .entityBox, g[id*="entity-"] rect, g[id^="entity"] rect,
+    svg[aria-roledescription="er"] .entityBox, svg[aria-roledescription="er"] g rect {
+        fill: var(--mmd-node-bg) !important; stroke: none !important;
+        rx: 4px !important; ry: 4px !important;
+        filter: var(--mmd-shadow-sm) !important;
+    }
+    .er .attributeBoxEven, .er .attributeBoxOdd {
+        fill: var(--mmd-node-bg) !important; stroke: none !important;
+    }
+
+    /* ── Gantt chart ──────────────────────────────────────── */
+    .titleText, text.titleText {
+        fill: var(--mmd-text) !important;
+        font-family: "Roboto","Noto Sans SC",-apple-system,sans-serif;
+        font-weight: 500; text-transform: uppercase; letter-spacing: 1.25px;
+    }
+    .sectionTitle, text.sectionTitle {
+        fill: var(--mmd-text-sub) !important;
+        font-family: "Roboto","Noto Sans SC",-apple-system,sans-serif; font-weight: 500;
+    }
+    .taskText, .taskTextOutsideRight, .taskTextOutsideLeft, text.taskText {
+        fill: var(--mmd-text) !important;
+        font-family: "Roboto","Noto Sans SC",-apple-system,sans-serif; font-weight: 400;
+    }
+    .task0, .task1, .task2, .task3, rect.task, rect[class*="task"],
+    svg[aria-roledescription="gantt"] rect.task, g.task rect {
+        stroke: none !important; rx: 4px !important;
+        filter: var(--mmd-shadow-sm) !important;
+    }
+    .taskText0, .taskText1, .taskText2, .taskText3 { fill: var(--mmd-text) !important; }
+    .grid .tick line { stroke: var(--mmd-border) !important; }
+    .grid path        { stroke: none              !important; }
+
+    /* ── Pie chart ────────────────────────────────────────── */
+    .pieCircle, circle.pieCircle { stroke: none !important; }
+    .pieTitleText, text.pieTitleText {
+        fill: var(--mmd-text) !important;
+        font-family: "Roboto","Noto Sans SC",-apple-system,sans-serif;
+        font-weight: 500; text-transform: uppercase; letter-spacing: 1.25px;
+    }
+    .legendText, text.legendText, text.legend {
+        fill: var(--mmd-text) !important;
+        font-family: "Roboto","Noto Sans SC",-apple-system,sans-serif; font-weight: 400;
+    }
+    .slice, path.slice, svg[aria-roledescription="pie"] path {
+        stroke: var(--mmd-canvas) !important; stroke-width: 2px !important;
+        filter: var(--mmd-shadow-sm) !important;
+    }
+    .pieChart .slice0 { fill: var(--mmd-accent-1) !important; }
+    .pieChart .slice1 { fill: var(--mmd-accent-2) !important; }
+    .pieChart .slice2 { fill: var(--mmd-accent-3) !important; }
+    .pieChart .slice3 { fill: var(--mmd-accent-4) !important; }
+    .pieChart .slice4 { fill: var(--mmd-accent-5) !important; }
+    .pieChart .slice5 { fill: var(--mmd-accent-6) !important; }
+
+    /* ── Journey diagram ──────────────────────────────────── */
+    .section0, .section1, .section2 {
+        fill: var(--mmd-node-bg) !important; stroke: none !important;
+        rx: 4px !important; filter: var(--mmd-shadow-sm);
+    }
+    .journey-section rect { rx: 4px !important; }
+
+    /* ── XYChart ──────────────────────────────────────────── */
+    .line-plot-0 path { stroke: var(--mmd-accent-1) !important; stroke-width: 3px !important; stroke-linecap: round; }
+    .line-plot-1 path { stroke: var(--mmd-accent-2) !important; stroke-width: 3px !important; stroke-linecap: round; }
+    .line-plot-2 path { stroke: var(--mmd-accent-3) !important; stroke-width: 3px !important; stroke-linecap: round; }
+    .bar-plot-0 rect { fill: var(--mmd-accent-1) !important; stroke: none !important; rx: 4px !important; filter: var(--mmd-shadow-sm); }
+    .bar-plot-1 rect { fill: var(--mmd-accent-2) !important; stroke: none !important; rx: 4px !important; filter: var(--mmd-shadow-sm); }
+    .bar-plot-2 rect { fill: var(--mmd-accent-3) !important; stroke: none !important; rx: 4px !important; filter: var(--mmd-shadow-sm); }
+    .ticks path { stroke: var(--mmd-border) !important; }
+    .chart-title text {
+        fill: var(--mmd-text) !important; font-weight: 500 !important; font-size: 18px !important;
+        font-family: "Roboto","Noto Sans SC",-apple-system,sans-serif;
+        text-transform: uppercase; letter-spacing: 1.25px;
+    }
+    .left-axis .label text, .bottom-axis .label text {
+        fill: var(--mmd-text-sub) !important; font-size: 13px !important;
+        font-family: "Roboto","Noto Sans SC",-apple-system,sans-serif;
+    }
+    .left-axis .title text, .bottom-axis .title text {
+        fill: var(--mmd-text) !important; font-size: 14px !important; font-weight: 500;
+        font-family: "Roboto","Noto Sans SC",-apple-system,sans-serif;
+    }
+    .legend text {
+        fill: var(--mmd-text) !important; font-size: 13px !important;
+        font-family: "Roboto","Noto Sans SC",-apple-system,sans-serif;
+    }
+
+    /* ── Global text fallback ─────────────────────────────── */
+    text {
+        fill: var(--mmd-text) !important;
+        font-family: "Roboto","Noto Sans SC",-apple-system,sans-serif;
+    }
+`;
+
+// ── Theme registry ────────────────────────────────────────────────────────────
+
+/** @type {Record<string, import('mermaid').MermaidConfig>} */
+export const MERMAID_THEMES = {
+    /**
+     * Material Design – light variant.
+     * White card surfaces, Roboto typography.
+     * Colours resolved from --mmd-* CSS tokens at paint-time.
+     */
+    material: {
+        theme: 'base',
+        themeVariables: {
+            background: '#ffffff',
+            primaryColor: '#ffffff',
+            primaryTextColor: 'rgba(0, 0, 0, 0.87)',
+            primaryBorderColor: '#e0e0e0',
+            lineColor: '#757575',
+            secondaryColor: '#ffffff',
+            tertiaryColor: '#ffffff',
+            fontFamily: '"Roboto", "Noto Sans SC", -apple-system, sans-serif',
+            fontSize: '14px',
+        },
+        themeCSS: MATERIAL_CSS,
+    },
+
+    /**
+     * Material Design – dark variant.
+     * Deep-navy surfaces (#2d2d44), elevated accent palette.
+     * themeCSS is identical to `material`; colours adapt automatically via
+     * --mmd-* tokens redefined under .greg[data-theme="dark"].
+     */
+    'material-dark': {
+        theme: 'base',
+        themeVariables: {
+            darkMode: true,
+            background: '#1e1e2e',
+            primaryColor: '#2d2d44',
+            primaryTextColor: 'rgba(255, 255, 255, 0.87)',
+            primaryBorderColor: '#3e3e5a',
+            lineColor: '#9090b8',
+            secondaryColor: '#2d2d44',
+            tertiaryColor: '#2d2d44',
+            fontFamily: '"Roboto", "Noto Sans SC", -apple-system, sans-serif',
+            fontSize: '14px',
+        },
+        themeCSS: MATERIAL_CSS,
+    },
+};
+
+/** The theme key used when no explicit theme is requested. */
+export const DEFAULT_MERMAID_THEME = 'material';
+
+/**
+ * Returns the best available theme key for the requested colour scheme.
+ *
+ * When `colorTheme === 'dark'`, tries `baseTheme + '-dark'` first.
+ * Falls back to `baseTheme` if the dark variant is not present in `themes`.
+ *
+ * @param {string}                   baseTheme  - e.g. 'material'
+ * @param {'light'|'dark'|undefined} colorTheme
+ * @param {Record<string,unknown>}   themes     - the merged theme map
+ * @returns {string}
+ */
+export function getColorSchemeTheme(baseTheme, colorTheme, themes) {
+    if (colorTheme === 'dark') {
+        const darkKey = `${baseTheme}-dark`;
+        if (darkKey in themes) return darkKey;
+    }
+    return baseTheme;
+}

package/src/lib/MarkdownDocs/navigationUtils.js

@@ -0,0 +1,22 @@
+/**
+ * Toggle a section on any section-row click and navigate to section index
+ * when the section has an index page.
+ */
+export function handleSectionClick(item, key, toggleSection, navigate) {
+    const EXTERNAL_RE = /^(?:[a-z][a-z\d+\-.]*:|\/\/)/i;
+
+    toggleSection(key);
+    if (item?.type === 'md' && item?.link) {
+        if (item.target === '_blank') {
+            window.open(item.link, '_blank', 'noopener,noreferrer');
+            return;
+        }
+
+        if (EXTERNAL_RE.test(item.link)) {
+            window.location.assign(item.link);
+            return;
+        }
+
+        navigate(item.link);
+    }
+}