coherent-docs-theme 1.0.0

package/README.md

@@ -0,0 +1,314 @@
+# Coherent Docs Theme
+
+A specialized [Starlight](https://starlight.astro.build/) theme designed for **Coherent Labs** documentation. It implements the **Gameface Design System**, offering a custom UI with distinct Dark/Light modes, sharp geometry, and integrated tooling for documentation management.
+
+## ✨ Features
+
+* **Gameface Design System:**
+  * **Dark Mode:** "Deep Teal" (`#0F2123`) backgrounds for content, Coherent Black (`#0A0A0A`) for navigation.
+  * **Light Mode:** Clean white and light grey palette.
+  * **Typography:** Pre-configured `Barlow Semi Condensed` (Headings) and `Karla` (Body).
+  * **Geometry:** Strictly sharp corners (`0px` border-radius) on all UI elements.
+* **Smart Navigation:**
+  * **Desktop:** Integrated header links alongside the logo.
+  * **Mobile:** Touch-friendly, horizontally scrollable navigation bar.
+  * **Sidebar:** Custom sidebar that prioritizes navigation links on mobile devices.
+* **Asset Injection:** Automatically injects the Coherent Gameface logo on the left side of the header unless explicitly disabled.
+* **Enhanced Components:**
+  * **Footer:** Automatic copyright year updating and legal links.
+  * **Progress Bar:** Optional reading progress indicator at the top of the page.
+* **Bundled Tools:**
+  * `starlight-heading-badges`: Adds badges to headings.
+  * `starlight-sidebar-topics`: Support for multi-instance documentation.
+
+## 📦 Installation
+
+Install the theme as a dependency in your documentation project:
+
+```bash
+npm install coherent-docs-theme
+```
+
+**Peer Dependencies**: Ensure your project meets the following requirements:
+
+* `astro: ^5.0.0`
+* `@astrojs/starlight: >=0.37.0`
+
+## 🚀 Usage
+
+Add the theme to your `astro.config.mjs`.
+
+⚠️ Important: The `coherentTheme` function returns an array of plugins. **You must use the spread operator (...) when adding it to the plugins list in Starlight.**
+
+```js
+// astro.config.mjs
+import { defineConfig } from 'astro/config';
+import starlight from '@astrojs/starlight';
+import coherentTheme from 'coherent-docs-theme';
+
+export default defineConfig({
+  integrations: [
+    starlight({
+      title: 'Gameface Documentation',
+      // Disable default credits to keep the footer clean
+      credits: false,
+
+      plugins: [
+        // ✅ CORRECT USAGE: Spread the array
+        ...coherentTheme({
+          documentationSearchTag: 'docs', // Tag to scope the search index for documentation content
+          showPageProgress: true,
+          // navLinks: [
+          //   { label: 'Roadmap', href: '/roadmap' },
+          //   { label: 'API', href: '/api' },
+          //   { label: 'Showcase', href: 'https://coherent-labs.com' }
+          // ], // Aditional links to display in the header if needed
+          // disableDefaultLogo: false, // Set true if you want to use your own logo
+          // replacesTitle: false, // Set true if you want to show the documentation title next to the logo in the header. Useful when using a custom logo that doesn't include the title in it.
+        }),
+      ],
+      
+      sidebar: [
+        {
+            label: 'Getting Started',
+            link: '/guides/getting-started'
+        }
+      ]
+    }),
+  ],
+});
+```
+
+## ⚙️ Configuration Options
+
+| Option                     | Type                     | Default | Description                                                                                                                                                                                |
+| -------------------------- | ------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **documentationSearchTag** | `string`                 | `''`    | (Required) A tag to scope the search index for the documentation content. Also, used to show a button for the search resources filter for the current documentation.                       |
+| **navLinks**               | `Array<{ label, href }>` | `[]`    | Links displayed in the header (desktop) and top-bar in the mobile menu (mobile).                                                                                                           |
+| **showPageProgress**       | `boolean`                | `false` | Shows a reading progress bar at the top of the page.                                                                                                                                       |
+| **disableDefaultLogo**     | `boolean`                | `false` | If false, injects the Gameface UI logo automatically if such is not defined in the Starlight config of the documentation. Set to true if you want to remove the logo entirely.             |
+| **replacesTitle**          | `boolean`                | `true`  | If true, the logo will replace the title in the header. Set to false if you want to show the title next to the logo. Useful when using a custom logo that doesn't include the title in it. |
+
+To override the default logo, simply provide your own in the Starlight configuration:
+
+```js
+starlight({
+    logo: {
+        dark: './path/to/dark-logo.svg',
+        light: './path/to/light-logo.svg',
+        // If your logo already includes the title, set this to true to avoid duplication.
+        replacesTitle: false,
+    },
+})
+```
+
+## 🛠️ Exported Utilities
+
+The theme exports helper functions to streamline sidebar configuration and versioning.
+
+* **generateVersionWithPackageJSON**
+
+Reads a `package.json` file and generates a sidebar item with a version badge.
+
+Usage:
+
+```js
+import { generateVersionWithPackageJSON } from 'coherent-docs-theme';
+
+// Inside astro.config.mjs -> starlight -> sidebar
+sidebar: [
+  {
+    label: 'Core Package',
+    items: [
+      // Note: This is async, ensure your config supports top-level await
+      await generateVersionWithPackageJSON(
+        '../packages/core/package.json', // Path to package.json
+        'https://www.npmjs.com/package/core' // (Optional) Link for the badge. If not provided, clicking the version will lead to the main documentation page.
+      ),
+      { label: 'Installation', link: '/core/install' }
+    ]
+  }
+]
+```
+
+**Note: Provide the absolute path to the package.json file using the `path` module to ensure it works correctly regardless of the current working directory.**
+
+* **generateDocsChangelog**
+
+Generates a standard changelog link object for the sidebar. In the documentation it will create link to the provided changelog file and it will automatically extract all the versions from the file to display it as separate versions in the sidebar and will add a badge with the latest version next to the label.
+
+```js
+import { generateDocsChangelog } from 'coherent-docs-theme';
+
+sidebar: [
+  // ...
+  generateDocsChangelog(path.join(__dirname, `./src/content/docs/changelog/index.mdx`))
+  // Output: { label: 'Changelog', link: '/changelog' }
+]
+```
+
+**Note: Provide the absolute path to the changelog file using the `path` module to ensure it works correctly regardless of the current working directory.**
+**Note: Use this method if you have a single documentation section. If you are using sidebar topics for multiple documentation sections, use `generateMultipleDocsChangelog` instead to ensure the changelog is correctly associated with the corresponding topic.**
+
+* **generateMultipleDocsChangelog**
+
+Generates a changelog page link for multiple documentation sections. Use this method to generate changelog when documentation is generated using sidebar topics plugin. In the documentation it will create link to the provided changelog file and it will automatically extract all the versions from the file to display it as separate versions in the sidebar and will add a badge with the latest version next to the label.
+
+```js
+import { generateDocsChangelog } from 'coherent-docs-theme';
+
+sidebar: [
+  // ...
+  generateMultipleDocsChangelog('my-docs-name', path.join(__dirname, `./src/content/docs/my-docs-name/changelog/index.mdx`)),
+  // Output: { label: 'Changelog', link: '/my-docs-name/changelog' }
+]
+```
+
+**Note: Provide the absolute path to the changelog file using the `path` module to ensure it works correctly regardless of the current working directory.**
+
+## 🎨 Styling & Customization
+
+The theme comes with a pre-configured styles.
+
+**Fonts**
+The theme automatically imports and applies:
+
+* **Headings**: `Barlow Semi Condensed`
+* **Body**: `Karla`
+
+Colors (CSS Variables)
+You can use these variables in your custom components to match the theme:
+
+```css
+/* Example Usage */
+.my-component {
+  background-color: var(--gameface-bg-panel); /* Adapts to Dark/Light mode */
+  color: var(--gameface-cyan); /* The primary accent color */
+  border: 1px solid var(--gameface-border);
+}
+```
+
+To override or add the default styles, create a CSS file and add it to the `customCss` array in your Starlight configuration:
+
+```js
+starlight({
+    // ...
+    customCss: [
+        './src/styles/custom.css', // Your custom styles
+    ],
+    // ...
+})
+```
+
+The variables and classes available can be found in the `styles.css` of the theme package. You can also inspect the generated CSS in the browser to see all available variables.
+
+## 📚 Multi-Instance Documentation (Sidebar Topics)
+
+To organize multiple distinct documentation sections (e.g., "E2E", "Vite Plugin") within a single site, use the starlight-sidebar-topics plugin.
+
+* **Define Topics:** Create an array of objects describing each section (`id`, `label`, `link`, `icon`, and `items`).
+* **Register Plugin:** Add it to the plugins array in your Starlight config.
+
+```js
+// astro.config.mjs
+import starlightSidebarTopics from 'starlight-sidebar-topics';
+
+const sideBarTopics = [
+  {
+    id: 'e2e',
+    label: 'Gameface E2E',
+    link: '/e2e/getting-started',
+    icon: 'rocket',
+    items: [
+       // Standard Starlight sidebar items (links, autogenerate, etc.)
+       { label: 'Getting Started', autogenerate: { directory: 'e2e/getting-started' } }
+    ]
+  },
+  // ... other topics
+];
+
+export default defineConfig({
+  integrations: [
+    starlight({
+      plugins: [
+        starlightSidebarTopics(sideBarTopics, {
+          // Optional: Map specific pages (like changelogs) to a topic manually
+          topics: { 
+            'e2e': ['/e2e/changelog'] 
+          }
+        })
+      ]
+    })
+  ]
+});
+```
+
+* 🔽 Sidebar Context Switcher (Dropdown)
+
+To display a dropdown menu at the top of the sidebar that allows users to switch between the defined topics, you must override the default Starlight Sidebar component with the specific component provided by the theme.
+
+Configuration:
+
+```js
+// astro.config.mjs
+import coherentTheme from 'coherent-docs-theme';
+
+export default defineConfig({
+  integrations: [
+    starlight({
+      plugins: [
+        ...coherentTheme(),
+      ],
+      // ...
+      components: {
+        // Point to the custom component exported by the theme
+        Sidebar: 'coherent-docs-theme/components/SidebarWithDropdown.astro',
+      },
+    }),
+  ],
+});
+```
+
+* Add redirects for each topic in `astro.config.mjs` to ensure the correct topic is highlighted when visiting the main page of each section (e.g., `/e2e` should redirect to `/e2e/getting-started`).
+
+```js
+export default defineConfig({
+    integrations: [
+        starlight({
+            // ...
+            redirects: {
+                '/e2e': '/e2e/getting-started',
+                // Add more redirects for other topics as needed
+            }
+        })
+    ]
+});
+```
+
+* Generate changelog links for sidebar topics
+
+To generate changelog links for each documentation section when using sidebar topics, use the `generateMultipleDocsChangelog` utility function provided by the theme. This function allows you to create a changelog link for each topic based on the corresponding changelog file.
+
+```js
+import { generateMultipleDocsChangelog } from 'coherent-docs-theme';
+
+
+const sideBarTopics = [
+  {
+    id: 'e2e',
+    label: 'Gameface E2E',
+    link: '/e2e/getting-started',
+    icon: 'rocket',
+    items: [
+       // Standard Starlight sidebar items (links, autogenerate, etc.)
+       { label: 'Getting Started', autogenerate: { directory: 'e2e/getting-started' } },
+       generateMultipleDocsChangelog('e2e', path.join(__dirname, `./src/content/docs/e2e/changelog/index.mdx`)),
+    ]
+  },
+  // ... other topics
+];
+```
+
+## 📝 License
+
+MIT © Coherent Labs

package/assets/gameface-ui-header-dark.svg

@@ -0,0 +1,5 @@
+<svg width="57" height="61" viewBox="0 0 57 61" fill="none"
+  xmlns="http://www.w3.org/2000/svg">
+  <path d="M5.23954 11.4401L29.838 34.5279L51.2458 25.7258L51.5478 25.1221L23.4275 6.84267L5.23954 11.4401Z" fill="white" stroke="#999999" stroke-width="0.7"/>
+  <path d="M29.5574 34.4221L28.7764 54.4039L47.8622 44.6475L51.5359 25.5635L29.5574 34.4221Z" fill="white" stroke="#999999" stroke-width="0.7"/>
+</svg>

package/assets/gameface-ui-header-light.svg

@@ -0,0 +1,5 @@
+<svg width="57" height="61" viewBox="0 0 57 61" fill="none"
+  xmlns="http://www.w3.org/2000/svg">
+  <path d="M5.23954 11.4401L29.838 34.5279L51.2458 25.7258L51.5478 25.1221L23.4275 6.84267L5.23954 11.4401Z" fill="white" fill-opacity="0.6" stroke="black" stroke-width="0.7"/>
+  <path d="M29.5574 34.4221L28.7764 54.4039L47.8622 44.6475L51.5359 25.5635L29.5574 34.4221Z" fill="white" fill-opacity="0.6" stroke="black" stroke-width="0.7"/>
+</svg>

package/components/Api.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="API"
+            badgeVariant="note"
+            engine={engine}
+            description={description}
+        >
+            <slot />
+        </ChangelogRow>
+    ) : (
+        <ChangelogRow
+            badgeText="API"
+            badgeVariant="note"
+            engine={engine}
+            description={description}
+        />
+    )
+}

package/components/BeforeAfter.astro

@@ -0,0 +1,124 @@
+---
+import { Image } from "astro:assets";
+import type { ImageMetadata } from "astro";
+
+interface Props {
+    src1: string | ImageMetadata;
+    src2: string | ImageMetadata;
+    alt1?: string;
+    alt2?: string;
+}
+
+const { src1, src2, alt1 = "Before image", alt2 = "After image" } = Astro.props;
+
+const isLocal1 = typeof src1 === "object";
+const isLocal2 = typeof src2 === "object";
+---
+
+<figure class="center">
+    <div class="image-slider">
+        <div class="slider-overlay">
+            {
+                isLocal1 ? (
+                    <Image src={src1 as ImageMetadata} alt={alt1} />
+                ) : (
+                    <img src={src1 as string} alt={alt1} />
+                )
+            }
+        </div>
+
+        {
+            isLocal2 ? (
+                <Image src={src2 as ImageMetadata} alt={alt2} />
+            ) : (
+                <img src={src2 as string} alt={alt2} />
+            )
+        }
+    </div>
+</figure>
+
+<style>
+    .center {
+        text-align: center;
+        margin: 2rem 0;
+    }
+
+    .image-slider {
+        position: relative;
+        display: inline-block;
+        line-height: 0;
+    }
+
+    .image-slider img {
+        user-select: none;
+        max-width: 70vw;
+        display: block;
+        height: auto;
+        margin: 0 !important;
+        padding: 0 !important;
+    }
+
+    .slider-overlay {
+        position: absolute;
+        top: 0;
+        bottom: 0;
+        left: 0;
+        width: 2%;
+        max-width: 100%;
+        overflow: hidden;
+        resize: horizontal;
+        border-right: 3px var(--before-after-line) solid;
+        box-sizing: border-box;
+        animation: slidejitter 2s ease-in-out 0.1s 1;
+    }
+
+    .slider-overlay:before {
+        position: absolute;
+        bottom: 3px;
+        right: 3px;
+        content: "";
+        display: block;
+        height: 3vw;
+        width: 3vw;
+        box-shadow: 3px 6px 2px 0 black;
+        overflow: hidden;
+        resize: horizontal;
+        background-clip: content-box;
+        background: linear-gradient(-45deg, white 50%, transparent 0);
+    }
+
+    @keyframes slidejitter {
+        25% {
+            width: 2%;
+        }
+        75% {
+            width: 5%;
+        }
+        100% {
+            width: 2%;
+        }
+    }
+
+    @media (min-width: 600px) {
+        .image-slider img {
+            max-width: 50vw;
+        }
+        .slider-overlay:before {
+            width: 2vw;
+            height: 2vw;
+        }
+    }
+
+    @media (min-width: 1200px) {
+        .image-slider img {
+            max-width: 40vw;
+        }
+        .slider-overlay {
+            width: 10%;
+        }
+        .slider-overlay:before {
+            width: 1vw;
+            height: 1vw;
+        }
+    }
+</style>

package/components/Details.astro

@@ -0,0 +1,37 @@
+---
+interface Props {
+    summary: string;
+    [key: string]: any;
+}
+
+const { summary, ...rest } = Astro.props;
+
+if (!summary) {
+    throw new Error("[Details Component] No summary provided!");
+}
+---
+
+<details {...rest}>
+    <summary>{summary}</summary>
+
+    <div class="details-content">
+        <slot />
+    </div>
+</details>
+
+<style>
+    .details-content {
+        margin-top: 1rem;
+        padding-left: 1rem;
+        border-left: 2px solid var(--sl-color-gray-5);
+    }
+
+    summary {
+        cursor: pointer;
+        font-weight: 600;
+    }
+
+    summary:hover {
+        color: var(--sl-color-accent);
+    }
+</style>

package/components/Enhancement.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="Enhancement"
+            badgeVariant="success"
+            engine={engine}
+            description={description}
+        >
+            <slot />
+        </ChangelogRow>
+    ) : (
+        <ChangelogRow
+            badgeText="Enhancement"
+            badgeVariant="success"
+            engine={engine}
+            description={description}
+        />
+    )
+}

package/components/Feature.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="Feature"
+            badgeVariant="note"
+            engine={engine}
+            description={description}
+        >
+            <slot />
+        </ChangelogRow>
+    ) : (
+        <ChangelogRow
+            badgeText="Feature"
+            badgeVariant="note"
+            engine={engine}
+            description={description}
+        />
+    )
+}

package/components/Figure.astro

@@ -0,0 +1,107 @@
+---
+import { Image } from "astro:assets";
+import type { ImageMetadata } from "astro";
+
+interface Props {
+    src: string | ImageMetadata;
+    alt?: string;
+    caption?: string;
+    title?: string;
+    class?: string;
+    link?: string;
+    target?: string;
+    rel?: string;
+    width?: number | string;
+    height?: number | string;
+    attr?: string;
+    attrlink?: string;
+}
+
+const {
+    src,
+    alt,
+    caption,
+    title,
+    class: className,
+    link,
+    target,
+    rel,
+    width,
+    height,
+    attr,
+    attrlink,
+} = Astro.props;
+
+const isLocal = typeof src === "object";
+const altText = alt || caption || "";
+---
+
+<figure class={className}>
+    {
+        link ? (
+            <a href={link} target={target} rel={rel}>
+                {isLocal ? (
+                    <Image
+                        src={src as ImageMetadata}
+                        alt={altText}
+                        title={title}
+                        width={width as any}
+                        height={height as any}
+                    />
+                ) : (
+                    <img
+                        src={src as string}
+                        alt={altText}
+                        title={title}
+                        width={width}
+                        height={height}
+                    />
+                )}
+            </a>
+        ) : isLocal ? (
+            <Image
+                src={src as ImageMetadata}
+                alt={altText}
+                title={title}
+                width={width as any}
+                height={height as any}
+            />
+        ) : (
+            <img
+                src={src as string}
+                alt={altText}
+                title={title}
+                width={width}
+                height={height}
+            />
+        )
+    }
+
+    {
+        (caption || attr) && (
+            <figcaption>
+                {caption && <p>{caption}</p>}
+
+                {attr && (
+                    <p>{attrlink ? <a href={attrlink}>{attr}</a> : attr}</p>
+                )}
+            </figcaption>
+        )
+    }
+</figure>
+
+<style>
+    figure {
+        margin: 2rem 0;
+        text-align: center;
+    }
+    figcaption {
+        margin-top: 0.5rem;
+        font-size: 0.9rem;
+        color: var(--sl-color-gray-3);
+        text-align: start;
+    }
+    figcaption p {
+        margin: 0;
+    }
+</style>