coherent-docs-theme 1.0.0

package/components/Fix.astro

@@ -0,0 +1,29 @@
+---
+import ChangelogRow, {
+    type ChangelogProps,
+} from "../internal-components/ChangelogRow.astro";
+
+interface Props extends ChangelogProps {}
+
+const { engine, description } = Astro.props;
+---
+
+{
+    Astro.slots.has("default") ? (
+        <ChangelogRow
+            badgeText="Fix"
+            badgeVariant="danger"
+            engine={engine}
+            description={description}
+        >
+            <slot />
+        </ChangelogRow>
+    ) : (
+        <ChangelogRow
+            badgeText="Fix"
+            badgeVariant="danger"
+            engine={engine}
+            description={description}
+        />
+    )
+}

package/components/GallerySlider.astro

@@ -0,0 +1,260 @@
+---
+import fs from "node:fs";
+import path from "node:path";
+import { Icon } from "@astrojs/starlight/components";
+import { Image } from "astro:assets";
+import type { ImageMetadata } from "astro";
+
+type CustomSlide = {
+    src: string | ImageMetadata;
+    link?: string;
+    description?: string;
+    alt?: string;
+};
+
+type GalleryItem = string | ImageMetadata | CustomSlide;
+
+interface Props {
+    dir?: string;
+    images?: GalleryItem[];
+    width?: string;
+    height?: string;
+    autoSlide?: number;
+}
+
+let {
+    dir,
+    images = [],
+    width = "100%",
+    height = "300px",
+    autoSlide = 0,
+} = Astro.props;
+
+let slides: CustomSlide[] = [];
+
+if (dir) {
+    const publicPath = path.join(process.cwd(), "public", dir);
+    try {
+        if (fs.existsSync(publicPath)) {
+            const files = fs.readdirSync(publicPath);
+            const imageFiles = files.filter((file) =>
+                /\.(png|jpe?g|gif|svg|webp)$/i.test(file),
+            );
+            slides.push(
+                ...imageFiles.map((file) => ({ src: `/${dir}/${file}` }))
+            );
+        }
+    } catch (e) {
+        console.error(`[Gallery] Error while reading the dir: ${publicPath}`, e);
+    }
+}
+
+images.forEach((item: any) => {
+    if (typeof item === "string") {
+        slides.push({ src: item });
+    } else if (
+        item.format !== undefined &&
+        item.width !== undefined &&
+        item.height !== undefined &&
+        item.description === undefined
+    ) {
+        slides.push({ src: item as ImageMetadata });
+    } else {
+        slides.push(item as CustomSlide);
+    }
+});
+
+if (slides.length === 0) {
+    console.warn("[Gallery] No images found.");
+}
+---
+
+<gallery-slider data-auto-slide={autoSlide}>
+    <div class="slide-window" style={`width: ${width}; height: ${height};`}>
+        <ul class="slides-list">
+            {
+                slides.map((slide) => {
+                    const isLocal = typeof slide.src === "object";
+                    const altText = slide.alt || "Gallery slide";
+
+                    const imgContent = isLocal ? (
+                        <Image src={slide.src as ImageMetadata} alt={altText} class="slide-img" />
+                    ) : (
+                        <img src={slide.src as string} alt={altText} class="slide-img" />
+                    );
+
+                    const slideBody = slide.link ? (
+                        <a href={slide.link} target="_blank" rel="noopener noreferrer" class="slide-link">
+                            {imgContent}
+                        </a>
+                    ) : (
+                        imgContent
+                    );
+
+                    return (
+                        <li class="slide">
+                            {slideBody}
+                            
+                            {slide.description && (
+                                <div class="slide-caption">
+                                    <p>{slide.description}</p>
+                                </div>
+                            )}
+                        </li>
+                    );
+                })
+            }
+        </ul>
+
+        <button class="nav left" aria-label="Previous image">
+            <Icon name="left-arrow" size="2rem" />
+        </button>
+        <button class="nav right" aria-label="Next image">
+            <Icon name="right-arrow" size="2rem" />
+        </button>
+    </div>
+</gallery-slider>
+
+<style>
+    gallery-slider {
+        display: block;
+        margin: 2rem auto;
+        max-width: 100%;
+    }
+
+    .slide-window {
+        position: relative;
+        overflow: hidden;
+        border-radius: 8px;
+        box-shadow: var(--sl-shadow-md);
+        background-color: var(--sl-color-gray-6);
+    }
+
+    .slides-list {
+        display: flex;
+        width: 100%;
+        height: 100%;
+        margin: 0 !important;
+        padding: 0 !important;
+        list-style: none !important;
+        transition: transform 0.5s ease-in-out;
+    }
+
+    .slide {
+        flex: 0 0 100%;
+        height: 100%;
+        position: relative;
+    }
+
+    .slide-link {
+        display: block;
+        width: 100%;
+        height: 100%;
+    }
+
+    .slide-img {
+        width: 100%;
+        height: 100%;
+        object-fit: contain;
+        display: block;
+        user-select: none;
+        margin-bottom: 0 !important;
+    }
+
+    .slide-caption {
+        position: absolute;
+        bottom: 0;
+        left: 0;
+        width: 100%;
+        background-color: rgba(0, 0, 0, 0.75);
+        color: white;
+        padding: 1rem 1.5rem;
+        text-align: center;
+        box-sizing: border-box;
+        pointer-events: none; 
+    }
+
+    .slide-caption p {
+        margin: 0 !important;
+        font-size: 0.95rem;
+        line-height: 1.4;
+    }
+
+    .nav {
+        position: absolute;
+        top: 50%;
+        transform: translateY(-50%);
+        background: rgba(0, 0, 0, 0.5);
+        color: white;
+        border: none;
+        border-radius: 50%;
+        width: 3rem;
+        height: 3rem;
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        cursor: pointer;
+        z-index: 10;
+        transition: background 0.2s ease;
+    }
+
+    .nav:hover {
+        background: rgba(0, 0, 0, 0.9);
+    }
+
+    .nav.left { left: 1rem; }
+    .nav.right { right: 1rem; }
+</style>
+
+<script>
+    class GallerySlider extends HTMLElement {
+        currentSlide: number = 0;
+        slidesList: HTMLElement | undefined;
+        slides: NodeListOf<Element> | undefined;
+        totalSlides: number = 0;
+        autoSlide: number = 0;
+        interval: NodeJS.Timeout | null = null;
+
+        connectedCallback() {
+            this.currentSlide = 0;
+            this.slidesList = this.querySelector(".slides-list") as HTMLElement;
+            this.slides = this.querySelectorAll(".slide");
+            this.totalSlides = this.slides.length;
+            this.autoSlide = parseInt(this.dataset.autoSlide || "0", 10);
+            this.interval = null;
+
+            if (this.totalSlides === 0) return;
+
+            this.querySelector(".left")?.addEventListener("click", () => this.move("back"));
+            this.querySelector(".right")?.addEventListener("click", () => this.move("forward"));
+
+            this.resetAutoSlide();
+        }
+
+        move(direction: "back" | "forward") {
+            if (direction === "back") {
+                this.currentSlide = (this.currentSlide - 1 + this.totalSlides) % this.totalSlides;
+            } else {
+                this.currentSlide = (this.currentSlide + 1) % this.totalSlides;
+            }
+            this.updateDOM();
+            this.resetAutoSlide();
+        }
+
+        updateDOM() {
+            if (this.slidesList)
+                this.slidesList.style.transform = `translateX(-${this.currentSlide * 100}%)`;
+        }
+
+        resetAutoSlide() {
+            if (this.autoSlide > 0) {
+                if (this.interval) clearInterval(this.interval);
+                this.interval = setInterval(() => this.move("forward"), this.autoSlide) as any;
+            }
+        }
+    }
+
+    if (!customElements.get("gallery-slider")) {
+        customElements.define("gallery-slider", GallerySlider);
+    }
+</script>

package/components/If.astro

@@ -0,0 +1,6 @@
+---
+interface Props {
+    product?: "gameface" | "prysm";
+    type?: "cxx" | "unity3d";
+}
+---

package/components/IfEnv.astro

@@ -0,0 +1,5 @@
+---
+interface Props {
+  env: 'development' | 'production' | string;
+}
+---

package/components/IfNot.astro

@@ -0,0 +1,6 @@
+---
+interface Props {
+    product?: "gameface" | "prysm";
+    type?: "cxx" | "unity3d";
+}
+---

package/components/IncludeSnippets.astro

@@ -0,0 +1,13 @@
+---
+interface Props {
+    release: string;
+    tag:
+        | "changelog"
+        | "rendering"
+        | "content_development"
+        | "migration"
+        | "core"
+        | "unreal_engine";
+    noBullets?: boolean;
+}
+---

package/components/Internal.astro

@@ -0,0 +1,3 @@
+---
+interface Props {}
+---

package/components/ProductName.astro

@@ -0,0 +1,13 @@
+---
+const rawProduct = import.meta.env.DOCS_PRODUCT || 'gameface';
+
+function humanize(str: string) {
+  if (!str) return '';
+  const cleanStr = str.replace(/[-_]/g, ' ');
+  return cleanStr.charAt(0).toUpperCase() + cleanStr.slice(1);
+}
+
+const productName = humanize(rawProduct);
+---
+
+{productName}

package/components/Release.astro

@@ -0,0 +1,68 @@
+---
+interface Props {
+    date: string;
+    version: string
+}
+
+const { date } = Astro.props;
+---
+
+<div class="release-container">
+    <hr />
+    <div class="release-date">
+        <a
+            href="https://coherent-labs.com/get-in-touch/"
+            target="_blank"
+            rel="noopener noreferrer"
+        >
+            <span>Released {date}</span>
+        </a>
+    </div>
+
+    <div class="table-wrapper">
+        <table class="table table-striped">
+            <tbody>
+                <slot />
+            </tbody>
+        </table>
+    </div>
+</div>
+
+<style>
+    .release-container {
+        margin-bottom: 2rem;
+    }
+
+    .release-date {
+        margin-bottom: 1.5rem;
+        font-size: 0.95rem;
+    }
+
+    .table-wrapper {
+        overflow-x: auto;
+    }
+
+    .table-wrapper :global(.table-striped td:first-child),
+    .table-wrapper :global(.table-striped th:first-child) {
+        padding-inline-start: 1rem !important;
+    }
+
+    .table-wrapper :global(.table-striped td:last-child),
+    .table-wrapper :global(.table-striped th:last-child) {
+        padding-inline-end: 1rem !important;
+    }
+
+    .table-wrapper :global(.table-striped td) {
+        padding-block: 0.75rem;
+        vertical-align: middle;
+    }
+
+    .table-striped {
+        width: 100%;
+        border-collapse: collapse;
+    }
+
+    .table-striped :global(tbody tr:nth-of-type(odd)) {
+        background-color: var(--sl-color-gray-6);
+    }
+</style>

package/components/SideBarWithDropdown.astro

@@ -0,0 +1,8 @@
+---
+import Default from '@astrojs/starlight/components/Sidebar.astro';
+import TopicsDropdown from 'starlight-sidebar-topics-dropdown/TopicsDropdown.astro';
+---
+
+<TopicsDropdown />
+
+<Default><slot /></Default>

package/components/Typeref.astro

@@ -0,0 +1,35 @@
+---
+interface Props {
+    title: string;
+    nativeRef?: string;
+    unityRef?: string;
+}
+
+const { title, nativeRef = "", unityRef = "" } = Astro.props;
+
+const currentType = import.meta.env.DOCS_TYPE || "";
+
+let resolvedPath = "";
+
+if (currentType === "cxx" && nativeRef !== "") {
+    resolvedPath = nativeRef;
+} else if (currentType === "unity3d" && unityRef !== "") {
+    resolvedPath = unityRef;
+}
+
+if (resolvedPath.endsWith(".mdx")) {
+    resolvedPath = resolvedPath.replace(/\.mdx$/, "");
+}
+
+if (resolvedPath.endsWith(".md")) {
+    resolvedPath = resolvedPath.replace(/\.md$/, "");
+}
+---
+
+{
+    resolvedPath !== "" ? (
+        <a href={resolvedPath}>{title}</a>
+    ) : (
+        <Fragment>{title}</Fragment>
+    )
+}

package/index.ts

@@ -0,0 +1,152 @@
+import type { StarlightPlugin } from '@astrojs/starlight/types';
+import { overrideComponents } from './internal/overrideComponents';
+import fs from 'fs';
+import path from 'path';
+import starlightHeadingBadges from 'starlight-heading-badges';
+import generateChangelogMultiple from './utils/changelogSideBarMultipleDocs';
+import generateChangelog from './utils/changelogSideBar';
+import type { CoherentThemeOptions } from './internal/themeConfig';
+import { fileURLToPath } from 'url';
+import { directives } from './remark-directives';
+import { getSortedCoherentReleases } from './utils/coherentReleases';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const defaultHeaderLinks = [
+  { href: 'https://docs.coherent-labs.com/cpp-gameface', label: 'Gameface' },
+  { href: 'https://docs.coherent-labs.com/cpp-prysm', label: 'Prysm' },
+  { href: 'https://starter.coherent-labs.com/', label: 'UI Starter Guide' },
+  { href: 'https://frontend-tools.coherent-labs.com', label: 'UI Tools' },
+  { href: 'https://gameface-ui.coherent-labs.com', label: 'Gameface UI' },
+  { href: 'https://coherent-labs.com/Documentation/ExporterLTS/', label: 'Adobe CC Tools' },
+];
+const defaultMergeIndex = [
+  {
+    bundlePath: "https://gameface-ui.coherent-labs.com/pagefind",
+    indexWeight: 0.5,
+    mergeFilter: {
+      resource: "Gameface UI"
+    }
+  },
+  {
+    bundlePath: "https://frontend-tools.coherent-labs.com/pagefind",
+    indexWeight: 0.5,
+    mergeFilter: {
+      resource: "UI Tools"
+    }
+  }
+]
+
+export default function coherentThemePlugin(options: CoherentThemeOptions = { documentationSearchTag: '' }): StarlightPlugin[] {
+  if (!options?.documentationSearchTag) {
+    throw new Error('Coherent docs theme plugin requires "documentationSearchTag"!')
+  }
+
+  let navLinks = defaultHeaderLinks;
+  for (const link of options.navLinks ?? []) {
+    navLinks.push(link)
+  }
+
+  const {
+    showPageProgress = false,
+    disableDefaultLogo = false,
+  } = options;
+
+  const corePlugin: StarlightPlugin = {
+    name: 'coherent-docs-theme',
+    hooks: {
+      'config:setup'({ config, logger, updateConfig, addIntegration }) {
+        logger.info('Initializing Coherent Theme...');
+
+        addIntegration({
+          name: 'coherent-docs-theme-integration',
+          hooks: {
+            'astro:config:setup': ({ updateConfig }) => {
+              updateConfig({
+                markdown: {
+                  remarkPlugins: [...directives],
+                },
+              });
+            }
+          }
+        });
+
+        process.env.COHERENT_THEME_CONFIG = JSON.stringify({ showPageProgress, navLinks, documentationSearchTag: options.documentationSearchTag });
+
+        const configUpdates: any = {
+          customCss: [...(config.customCss ?? []), 'coherent-docs-theme/styles'],
+          components: overrideComponents(
+            config,
+            ['Header', 'ThemeSelect', 'Footer', 'Search'],
+            logger,
+          ),
+          head: config.head || [],
+        };
+        if (!disableDefaultLogo && !config.logo) {
+          configUpdates.logo = {
+            dark: path.join(__dirname, 'assets/gameface-ui-header-dark.svg'),
+            light: path.join(__dirname, 'assets/gameface-ui-header-light.svg'),
+            replacesTitle: options.replacesTitle ?? true,
+          };
+        }
+
+        configUpdates.head.push({
+          tag: 'meta',
+          attrs: {
+            'data-pagefind-filter': 'resource[content]',
+            content: options.documentationSearchTag
+          }
+        })
+
+        configUpdates.pagefind = {
+          indexWeight: 2,
+          mergeIndex: defaultMergeIndex.filter(merge => {
+            const resource = merge.mergeFilter.resource;
+            return resource !== options.documentationSearchTag;
+          })
+        };
+
+        updateConfig(configUpdates);
+      },
+    },
+  };
+
+  const plugins = [
+    starlightHeadingBadges(),
+    corePlugin,
+  ];
+
+  return plugins
+}
+
+export function generateVersion(version: string, link?: string) {
+  const config: { label: string; link: string; attrs?: { target: string }; badge?: { text: string; variant: "note" | "danger" | "success" | "caution" | "tip" | "default" } } = {
+    label: 'Version:',
+    link: '/',
+    badge: {
+      text: `${version}`,
+      variant: 'tip',
+    },
+  }
+
+  if (link) {
+    config.link = link;
+    config.attrs = { target: '_blank' };
+  }
+
+  return config;
+}
+
+export async function generateVersionWithPackageJSON(packagePath: string, link?: string) {
+  if (!fs.existsSync(packagePath)) throw new Error(`Version not found in ${packagePath}`);
+  const packageContent = fs.readFileSync(packagePath, 'utf-8');
+  const packageJson = JSON.parse(packageContent);
+  const version = packageJson?.version;
+  if (!version) throw new Error(`Version not defined in ${packagePath}`);
+
+  return generateVersion(version, link);
+}
+
+export const generateMultipleDocsChangelog = generateChangelogMultiple;
+export const generateDocsChangelog = generateChangelog;
+export const getCoherentReleases = getSortedCoherentReleases;

package/internal/overrideComponents.ts

@@ -0,0 +1,29 @@
+import type { HookParameters } from '@astrojs/starlight/types'
+import type { AstroIntegrationLogger } from 'astro'
+
+export function overrideComponents(
+    starlightConfig: StarlightUserConfig,
+    overrides: ComponentOverride[],
+    logger: AstroIntegrationLogger,
+): StarlightUserConfig['components'] {
+    const components = { ...starlightConfig.components }
+
+    for (const override of overrides) {
+        const name = typeof override === 'string' ? override : override.name
+        if (starlightConfig.components?.[name]) {
+            logger.info(`Overriding coherent-docs-theme's \`<${name}>\` component with \`${starlightConfig.components?.[name]}\`.`)
+            continue
+        }
+        components[name] = `coherent-docs-theme/overrides/${name}.astro`
+    }
+
+    return components
+}
+
+type StarlightUserConfig = HookParameters<'config:setup'>['config']
+
+type ComponentOverride =
+    | keyof NonNullable<StarlightUserConfig['components']>
+    | {
+        name: keyof NonNullable<StarlightUserConfig['components']>
+    }

package/internal/themeConfig.ts

@@ -0,0 +1,21 @@
+export interface CoherentThemeOptions {
+    documentationSearchTag: string
+    showPageProgress?: boolean;
+    navLinks?: Array<{ label: string; href: string }>;
+    disableDefaultLogo?: boolean;
+    replacesTitle?: boolean
+}
+
+export default function getThemeConfig(): CoherentThemeOptions {
+    let themeConfig = { documentationSearchTag: '', showPageProgress: false, navLinks: [], disableDefaultLogo: false } as CoherentThemeOptions;
+
+    if (process.env.COHERENT_THEME_CONFIG) {
+        try {
+            themeConfig = { ...themeConfig, ...JSON.parse(process.env.COHERENT_THEME_CONFIG) };
+        } catch (e) {
+            console.error("Failed to parse Coherent Theme config");
+        }
+    }
+
+    return themeConfig;
+}