coherent-docs-theme 1.0.0

package/overrides/Search.astro

@@ -0,0 +1,234 @@
+---
+import DefaultSearch from '@astrojs/starlight/components/Search.astro';
+
+import getThemeConfig from "../internal/themeConfig";
+const { documentationSearchTag } = getThemeConfig();
+const isDev = import.meta.env.DEV;
+---
+
+<DefaultSearch {...Astro.props} />
+
+<style is:global>
+.pagefind-ui__result-excerpt mark {
+  font-weight: 900 !important;
+  background-color: rgba(255, 215, 0, 0.3) !important;
+  color: var(--sl-color-white) !important;
+  padding: 0 2px;
+  border-radius: 2px;
+}
+
+.pagefind-ui__result-title::before,
+.pagefind-ui__result-link::before,
+.pagefind-ui__result-nested::before {
+  display: none !important;
+  content: none !important;
+}
+
+#starlight__search .pagefind-ui__result-inner>.pagefind-ui__result-title {
+  padding-inline-start: 1rem !important;
+}
+
+#starlight__search .pagefind-ui__result-inner>.pagefind-ui__result-nested {
+  padding-inline-start: 2rem !important;
+}
+
+.pagefind-ui__filter-checkbox,
+.pagefind-ui__filter-checkbox::before {
+  display: none !important;
+}
+
+.pagefind-ui__filter-value::before {
+  display: none !important;
+}
+
+.pagefind-ui__filter-label::before,
+.pagefind-ui__filter-label svg {
+  display: none !important;
+  content: none !important;
+}
+
+.pagefind-ui__filter-label {
+  display: inline-flex !important;
+  align-items: center !important;
+  justify-content: center !important;
+  cursor: pointer !important;
+  padding: 0.4rem 1rem !important;
+  margin: 0.2rem 0.3rem 0.2rem 0 !important;
+  font-size: inherit !important;
+  font-weight: 600 !important;
+  background-color: var(--sl-color-bg-nav) !important;
+  border: 1px solid var(--sl-color-gray-5) !important;
+  color: var(--sl-color-gray-3) !important;
+  transition: all 0.2s ease !important;
+}
+
+.pagefind-ui__filter-label:hover {
+  border-color: var(--sl-color-gray-2) !important;
+  color: var(--sl-color-white) !important;
+}
+
+.pagefind-ui__filter-checkbox:checked+.pagefind-ui__filter-label {
+  background-color: var(--sl-color-accent) !important;
+  border-color: var(--sl-color-accent) !important;
+  color: var(--gameface-bg-main) !important;
+}
+
+.custom-docs-badge {
+  color: white;
+  padding: 2px 8px;
+  border-radius: 12px;
+  font-size: 11px;
+  margin-right: 10px;
+  vertical-align: middle;
+  font-weight: bold;
+  text-transform: uppercase;
+  letter-spacing: 0.5px;
+}
+
+@media (min-width: 50rem) {
+  site-search dialog {
+    max-width: 90%;
+  }
+}
+</style>
+
+{!isDev &&
+<script is:inline define:vars={{documentationSearchTag}}>
+    const badgesConfig = {
+        "frontend-tools.coherent-labs.com/e2e": { text: "UI Tools | Gameface E2E", color: "#007aaa" },
+        "frontend-tools.coherent-labs.com/interaction-manager": { text: "UI Tools | Interaction Manager", color: "#007abb" },
+        "frontend-tools.coherent-labs.com/gameface-vite-plugin": { text: "UI Tools | Gameface Vite Plugin", color: "#007acc" },
+        "frontend-tools.coherent-labs.com/vite-solid-style-to-css-plugin": { text: "UI Tools | Solid Style to CSS Plugin", color: "#007add" },
+        "frontend-tools.coherent-labs.com/data-binding-autocomplete": { text: "UI Tools | Data Binding Autocomplete", color: "#007aee" },
+        "frontend-tools.coherent-labs.com/frontend-tools.coherent-labs.com": { text: "UI Tools", color: "#007aff" },
+        "gameface-ui": { text: "Gameface UI", color: "#e24a4a" },
+    }
+
+    function setupSearchInputListener(searchInput, pagefind) {
+        if (!searchInput || searchInput.dataset.countListener) return;
+        
+        searchInput.dataset.countListener = "true";
+        searchInput.addEventListener("input", async (e) => {
+            const term = e.target.value;
+            if (!term) {
+                window.__pagefindTrueCounts = {};
+                return;
+            }
+            const search = await pagefind.search(term);
+            window.__pagefindTrueCounts = search.filters?.resource || {};
+            searchInput.dataset.forceUpdate = Date.now();
+        });
+    }
+
+    function applyBadgesToResults(container) {
+        const resultTitles = container.querySelectorAll(".pagefind-ui__result-inner > p.pagefind-ui__result-title:not([data-badged])");
+        if (resultTitles.length === 0) return;
+
+        resultTitles.forEach((titleElement) => {
+            titleElement.dataset.badged = "true";
+            const link = titleElement.querySelector("a");
+            if (!link) return;
+
+            let badgeText = documentationSearchTag;
+            let badgeColor = "#883aea";
+
+            for (const key in badgesConfig) {
+                if (link.href.includes(key)) {
+                    badgeText = badgesConfig[key].text;
+                    badgeColor = badgesConfig[key].color;
+                    break;
+                }
+            }
+
+            const badge = document.createElement("span");
+            badge.className = "custom-docs-badge";
+            badge.textContent = badgeText;
+            badge.style.backgroundColor = badgeColor;
+            titleElement.prepend(badge);
+        });
+    }
+
+    function applyDefaultFilter(checkboxes) {
+        if (checkboxes.length === 0 || window.__pagefindDefaultApplied) return;
+        
+        window.__pagefindDefaultApplied = true;
+        const defaultCb = Array.from(checkboxes).find(cb => cb.value === documentationSearchTag);
+        
+        if (defaultCb && !defaultCb.checked) {
+            defaultCb.checked = true;
+            defaultCb.dispatchEvent(new Event("change", { bubbles: true }));
+        }
+    }
+
+    function processFiltersAndCounts(checkboxes, searchInput, observer, searchContainer) {
+        checkboxes.forEach((cb) => {
+            if (!cb.dataset.radioFixed) {
+                cb.dataset.radioFixed = "true";
+                cb.addEventListener("change", (e) => {
+                    if (e.target.checked) {
+                        checkboxes.forEach((other) => {
+                            if (other !== e.target && other.checked) {
+                                other.checked = false; 
+                                other.dispatchEvent(new Event("change", { bubbles: true }));
+                            }
+                        });
+                    }
+                });
+            }
+
+            if (window.__pagefindTrueCounts && searchInput && searchInput.value) {
+                const docName = cb.value;
+                const trueCount = window.__pagefindTrueCounts[docName] || 0;
+                const label = searchContainer.querySelector(`[for="resource-${docName}"]`);
+                
+                if(!label) return;
+
+                const currentText = label.textContent;
+                const newText = currentText.replace(/\(\d+\)/, `(${trueCount})`);
+
+                if (currentText !== newText) {
+                    observer.disconnect();
+                    label.textContent = newText;
+                    observer.observe(searchContainer, { childList: true, subtree: true });
+                }
+            }
+        });
+    }
+
+    document.addEventListener("DOMContentLoaded", async () => {
+        const searchContainer = document.getElementById("starlight__search");
+        if (!searchContainer) return;
+
+        try {
+            const pagefind = await import("/pagefind/pagefind.js");
+            window.__pagefindTrueCounts = {};
+
+            let frameRequested = false;
+
+            const observer = new MutationObserver((mutations) => {
+                const hasInterestingChanges = mutations.some(m => m.addedNodes.length > 0);
+                if (!hasInterestingChanges && !window.__pagefindTrueCounts) return;
+
+                if (frameRequested) return;
+                frameRequested = true;
+
+                requestAnimationFrame(() => {
+                    const searchInput = searchContainer.querySelector(".pagefind-ui__search-input");
+                    const checkboxes = searchContainer.querySelectorAll(".pagefind-ui__filter-checkbox");
+
+                    setupSearchInputListener(searchInput, pagefind);
+                    applyBadgesToResults(searchContainer);
+                    applyDefaultFilter(checkboxes);
+                    processFiltersAndCounts(checkboxes, searchInput, observer, searchContainer);
+                    
+                    frameRequested = false;
+                });
+            });
+
+            observer.observe(searchContainer, { childList: true, subtree: true });
+        } catch (e) {
+            console.warn("Failed to load raw Pagefind API for counts", e);
+        }
+    });
+</script>
+}

package/overrides/ThemeSelect.astro

@@ -0,0 +1,218 @@
+---
+import crypto from "node:crypto";
+
+const id = `moon-mask-${crypto.randomBytes(4).toString("hex")}`;
+
+// https://web.dev/building-a-theme-switch-component/
+// https://github.com/withastro/starlight/blob/9237581c766f68fbb3ce5f9401ca2046f106c7d5/packages/starlight/components/ThemeSelect.astro
+---
+
+<starlight-coherent-docs-theme-select>
+  <button
+    aria-label={Astro.locals.t("themeSelect.accessibleLabel")}
+    aria-live="polite"
+    class="sl-flex"
+    title={Astro.locals.t("themeSelect.accessibleLabel")}
+  >
+    <svg aria-hidden="true" height="16" viewBox="0 0 24 24" width="16">
+      <mask class="moon" id={id}>
+        <rect x="0" y="0" width="100%" height="100%" fill="white"></rect>
+        <circle cx="24" cy="10" r="6" fill="black"></circle>
+      </mask>
+      <circle class="sun" cx="12" cy="12" r="6" mask={`url(#${id})`}></circle>
+      <g class="sun-beams" stroke="currentColor">
+        <line x1="12" y1="1" x2="12" y2="3"></line>
+        <line x1="12" y1="21" x2="12" y2="23"></line>
+        <line x1="4.22" y1="4.22" x2="5.64" y2="5.64"></line>
+        <line x1="18.36" y1="18.36" x2="19.78" y2="19.78"></line>
+        <line x1="1" y1="12" x2="3" y2="12"></line>
+        <line x1="21" y1="12" x2="23" y2="12"></line>
+        <line x1="4.22" y1="19.78" x2="5.64" y2="18.36"></line>
+        <line x1="18.36" y1="5.64" x2="19.78" y2="4.22"></line>
+      </g>
+    </svg>
+  </button>
+</starlight-coherent-docs-theme-select>
+
+<style>
+  starlight-coherent-docs-theme-select {
+    --sl-rapide-theme-select-animation-duration: 400ms;
+    --sl-rapide-theme-select-ease-elastic: cubic-bezier(0.5, 1.25, 0.75, 1.25);
+
+    align-self: stretch;
+  }
+
+  button {
+    align-items: center;
+    background-color: transparent;
+    border: none;
+    cursor: pointer;
+    height: 100%;
+  }
+
+  svg {
+    stroke-linecap: round;
+  }
+
+  svg :is(.moon, .sun, .sun-beams) {
+    transform-origin: center;
+  }
+
+  svg :is(.moon, .sun) {
+    fill: var(--sl-color-text-accent);
+  }
+
+  svg .sun-beams {
+    stroke: var(--sl-color-text-accent);
+    stroke-width: 2px;
+  }
+
+  button:is(:hover, :focus-visible) svg :is(.moon, .sun) {
+    fill: var(--sl-color-accent-high);
+  }
+
+  button:is(:hover, :focus-visible) svg .sun-beams {
+    stroke: var(--sl-color-accent-high);
+  }
+
+  :global([data-theme="dark"]) svg .sun {
+    transform: scale(1.75);
+  }
+
+  :global([data-theme="dark"]) svg .sun-beams {
+    opacity: 0;
+  }
+
+  :global([data-theme="dark"]) svg .moon circle {
+    transform: translateX(-7px);
+  }
+
+  @supports (cx: 1) {
+    :global([data-theme="dark"]) svg .moon circle {
+      cx: 17;
+      transform: translateX(0);
+    }
+  }
+
+  @media (prefers-reduced-motion: no-preference) {
+    svg .sun {
+      transition: transform var(--sl-rapide-theme-select-animation-duration)
+        var(--sl-rapide-theme-select-ease-elastic);
+    }
+
+    svg .sun-beams {
+      transition:
+        opacity var(--sl-rapide-theme-select-animation-duration) ease,
+        transform var(--sl-rapide-theme-select-animation-duration)
+          var(--sl-rapide-theme-select-ease-elastic);
+    }
+
+    svg .moon circle {
+      transition: transform
+        calc(var(--sl-rapide-theme-select-animation-duration) / 2) ease-out;
+    }
+
+    @supports (cx: 1) {
+      svg .moon circle {
+        transition: cx
+          calc(var(--sl-rapide-theme-select-animation-duration) / 2) ease-out;
+      }
+    }
+
+    :global([data-theme="dark"]) svg .sun {
+      transform: scale(1.75);
+      transition-duration: calc(
+        var(--sl-rapide-theme-select-animation-duration) / 2
+      );
+      transition-timing-function: ease;
+    }
+
+    :global([data-theme="dark"]) svg .sun-beams {
+      transform: rotateZ(-25deg);
+      transition-duration: calc(
+        var(--sl-rapide-theme-select-animation-duration) / 4
+      );
+    }
+
+    :global([data-theme="dark"]) svg .moon circle {
+      transition-delay: calc(
+        var(--sl-rapide-theme-select-animation-duration) / 4
+      );
+      transition-duration: var(--sl-rapide-theme-select-animation-duration);
+    }
+  }
+</style>
+
+{/* Inlined to avoid FOUC. Uses global scope from `ThemeProvider.astro` */}
+<script is:inline>
+  StarlightThemeProvider.updatePickers();
+</script>
+
+<script>
+  type Theme = "auto" | "dark" | "light";
+
+  /** Key in `localStorage` to store color theme preference at. */
+  const storageKey = "starlight-theme";
+
+  /** Get a typesafe theme string from any JS value (unknown values are coerced to `'auto'`). */
+  function parseTheme(theme: unknown): Theme {
+    return theme === "auto" || theme === "dark" || theme === "light"
+      ? theme
+      : "auto";
+  }
+
+  /** Load the user’s preference from `localStorage`. */
+  function loadTheme(): Theme {
+    return parseTheme(
+      typeof localStorage !== "undefined" && localStorage.getItem(storageKey),
+    );
+  }
+
+  /** Store the user’s preference in `localStorage`. */
+  function storeTheme(theme: Theme): void {
+    if (typeof localStorage !== "undefined") {
+      localStorage.setItem(
+        storageKey,
+        theme === "light" || theme === "dark" ? theme : "",
+      );
+    }
+  }
+
+  /** Get the preferred system color scheme. */
+  function getPreferredColorScheme(): Theme {
+    return matchMedia("(prefers-color-scheme: light)").matches
+      ? "light"
+      : "dark";
+  }
+
+  /** Update select menu UI, document theme, and local storage state. */
+  function onThemeChange(theme: Theme): void {
+    StarlightThemeProvider.updatePickers(theme);
+    document.documentElement.dataset["theme"] =
+      theme === "auto" ? getPreferredColorScheme() : theme;
+    storeTheme(theme);
+  }
+
+  // React to changes in system color scheme.
+  matchMedia(`(prefers-color-scheme: light)`).addEventListener("change", () => {
+    if (loadTheme() === "auto") onThemeChange("auto");
+  });
+
+  customElements.define(
+    "starlight-coherent-docs-theme-select",
+    class CoherentThemeSelect extends HTMLElement {
+      constructor() {
+        super();
+        onThemeChange(loadTheme());
+        const button = this.querySelector("button");
+        button?.addEventListener("click", () => {
+          const theme = parseTheme(document.documentElement.dataset["theme"]);
+          const newTheme =
+            theme === "dark" ? "light" : theme === "light" ? "dark" : "auto";
+          onThemeChange(newTheme);
+          button?.setAttribute("aria-label", `${newTheme} theme`);
+        });
+      }
+    },
+  );
+</script>

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "coherent-docs-theme",
+  "version": "1.0.0",
+  "license": "MIT",
+  "description": "Theme for all the coherent documentations",
+  "author": "CoherentLabs",
+  "type": "module",
+  "scripts": {
+    "publish:package": "npm i && npm publish"
+  },
+  "exports": {
+    ".": "./index.ts",
+    "./styles": "./styles.css",
+    "./components/*.astro": "./components/*.astro",
+    "./overrides/*.astro": "./overrides/*.astro",
+    "./assets/*": "./assets/*"
+  },
+  "devDependencies": {
+    "@astrojs/starlight": "^0.37.6",
+    "@types/mdast": "^4.0.4",
+    "@types/unist": "^3.0.3",
+    "astro": "^5.17.1"
+  },
+  "dependencies": {
+    "starlight-heading-badges": "^0.6.1",
+    "starlight-links-validator": "^0.19.2",
+    "starlight-sidebar-topics": "^0.6.2",
+    "starlight-sidebar-topics-dropdown": "^0.5.2",
+    "gray-matter": "^4.0.3"
+  },
+  "peerDependencies": {
+    "@astrojs/starlight": ">=0.37"
+  },
+  "engines": {
+    "node": "^18.17.1 || ^20.3.0 || >=21.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://github.com/CoherentLabs/frontend-tools/tree/master/docs-theme/packages/coherent-docs-theme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/CoherentLabs/frontend-tools/coherent-docs-theme.git",
+    "directory": "packages/coherent-docs-theme"
+  }
+}

package/remark-directives/if.ts

@@ -0,0 +1,51 @@
+import { visit } from 'unist-util-visit';
+import type { Root } from 'mdast';
+
+const ifDirectiveNames = ['If', 'IfNot', 'IfEnv']
+export function remarkIfDirective() {
+    return (tree: Root) => {
+        visit(tree, ['mdxJsxFlowElement', 'mdxJsxTextElement'], (node: any, index, parent) => {
+            const nodeName = node.name;
+            if (!ifDirectiveNames.includes(nodeName) || index === undefined || !parent) return;
+
+            const attrs: Record<string, string | undefined> = {};
+            node.attributes?.forEach((attr: any) => {
+                if (attr.type === 'mdxJsxAttribute' && typeof attr.value === 'string') {
+                    attrs[attr.name] = attr.value;
+                }
+            });
+
+            const { product, type, env } = attrs;
+
+            const currentProduct = process.env.DOCS_PRODUCT;
+            const currentType = process.env.DOCS_TYPE;
+            const currentEnv = process.env.MODE;
+
+            let shouldRender = true;
+
+            switch (nodeName) {
+                case 'If':
+                    if (product && product !== currentProduct) shouldRender = false;
+                    if (type && type !== currentType) shouldRender = false;
+                    break;
+
+                case 'IfNot':
+                    if (product && product === currentProduct) shouldRender = false;
+                    if (type && type === currentType) shouldRender = false;
+                    break;
+
+                case 'IfEnv':
+                    if (env && env !== currentEnv) shouldRender = false;
+                    break;
+            }
+
+            if (shouldRender) {
+                parent.children.splice(index, 1, ...node.children);
+                return index;
+            } else {
+                parent.children.splice(index, 1);
+                return index;
+            }
+        });
+    };
+}

package/remark-directives/includeSnippets.ts

@@ -0,0 +1,120 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import matter from 'gray-matter';
+import { visit } from 'unist-util-visit';
+import { fromMarkdown } from 'mdast-util-from-markdown';
+import { mdxFromMarkdown } from 'mdast-util-mdx';
+import { mdxjs } from 'micromark-extension-mdxjs';
+import type { Root, Content, Heading } from 'mdast';
+import type { MdxJsxFlowElement } from 'mdast-util-mdx-jsx';
+
+type SnippetTag = "changelog" | "rendering" | "content_development" | "migration" | "core" | "unreal_engine";
+
+interface TagConfig {
+    title: string;
+    level: 1 | 2 | 3;
+}
+
+const TAG_CONFIG: Record<SnippetTag, TagConfig> = {
+    changelog: { title: "Changelog", level: 1 },
+    migration: { title: "Migration guide", level: 1 },
+    content_development: { title: "Content Development", level: 2 },
+    core: { title: "Core", level: 2 },
+    rendering: { title: "Rendering", level: 2 },
+    unreal_engine: { title: "Unreal Engine", level: 2 },
+};
+
+const isDev = process.env.NODE_ENV === 'development' || process.env.MODE === 'development';
+
+export function remarkIncludeSnippets() {
+    return (tree: Root) => {
+
+        visit(tree, 'mdxJsxFlowElement', (node: MdxJsxFlowElement, index, parent) => {
+            if (node.name !== 'IncludeSnippets' || index === undefined || !parent) return;
+
+            const attrs = Object.fromEntries(
+                node.attributes.map((attr) => {
+                    if ('name' in attr && 'value' in attr) {
+                        return [attr.name, attr.value];
+                    }
+                    return [];
+                })
+            );
+
+            const release = attrs.release as string;
+            const tag = attrs.tag as SnippetTag;
+            const noBullets = attrs.noBullets === 'true' || attrs.noBullets === true;
+
+            const currentConfig = TAG_CONFIG[tag];
+            if (!currentConfig || !release) return;
+
+            const folderName = release === 'next_release' ? 'next_release' : `Release_${release}`;
+            const releaseDir = path.resolve(`./src/content/docs/releases/${folderName}/`);
+
+            if (release === 'next_release' && !isDev) {
+                parent.children.splice(index, 1);
+                return index;
+            }
+
+            const injectedNodes: Content[] = [];
+
+            if (fs.existsSync(releaseDir)) {
+                const files = fs.readdirSync(releaseDir);
+                const matchingSnippets: Array<{ data: any; content: string }> = [];
+
+                for (const fileName of files) {
+                    if (!fileName.startsWith('_')) continue;
+                    if (!fileName.endsWith('.md') && !fileName.endsWith('.mdx')) continue;
+
+                    const filePath = path.join(releaseDir, fileName);
+                    const fileContent = fs.readFileSync(filePath, 'utf-8');
+                    const { data, content } = matter(fileContent);
+
+                    if (data?.tag === tag && data?.draft !== true) {
+                        matchingSnippets.push({ data, content });
+                    }
+                }
+
+                matchingSnippets.sort((a, b) => (a.data.weight || 0) - (b.data.weight || 0));
+
+                if (matchingSnippets.length > 0) {
+                    injectedNodes.push({
+                        type: 'heading',
+                        depth: currentConfig.level as Heading['depth'],
+                        data: {
+                            hProperties: {
+                                id: currentConfig.title.toLowerCase().replace(/[^a-z0-9]+/g, "-")
+                            }
+                        },
+                        children: [{ type: 'text', value: currentConfig.title }]
+                    } as Heading);
+
+                    for (const snippet of matchingSnippets) {
+                        if (!noBullets && snippet.data.title) {
+                            injectedNodes.push({
+                                type: 'heading',
+                                depth: 3,
+                                children: [{ type: 'text', value: snippet.data.title }]
+                            } as Heading);
+                        }
+
+                        const snippetAst = fromMarkdown(snippet.content, {
+                            extensions: [mdxjs()],
+                            mdastExtensions: [mdxFromMarkdown()]
+                        });
+
+                        injectedNodes.push(...(snippetAst.children as Content[]));
+                    }
+                }
+            }
+
+            if (injectedNodes.length > 0) {
+                parent.children.splice(index, 1, ...injectedNodes);
+                return index + injectedNodes.length;
+            } else {
+                parent.children.splice(index, 1);
+                return index;
+            }
+        });
+    };
+}

package/remark-directives/index.ts

@@ -0,0 +1,13 @@
+import remarkDirective from 'remark-directive';
+import { remarkIfDirective } from "./if";
+import { remarkIncludeSnippets } from "./includeSnippets";
+import { remarkReleaseDirective } from './release';
+import { remarkInternalDirective } from './internal';
+
+export const directives = [
+    remarkDirective,
+    remarkIfDirective,
+    remarkInternalDirective,
+    remarkReleaseDirective,
+    remarkIncludeSnippets
+];