@grove-dev/starlight 0.1.9

package/components/overrides/parts/NavBar.astro

@@ -0,0 +1,110 @@
+---
+import { AstroError } from 'astro/errors';
+import userConfig from 'virtual:lucode-starlight-config';
+import starlightConfig from 'virtual:starlight/user-config';
+import { getRelativeLocaleUrl } from 'astro:i18n';
+
+const currentPath = Astro.url.pathname;
+
+const defaultLang =
+    starlightConfig.defaultLocale?.lang || starlightConfig.defaultLocale?.locale || 'en';
+
+export function getTranslation(
+    translations: Record<string, string>,
+    link: string,
+    description: string
+) {
+    const defaultTranslation = translations[defaultLang];
+
+    if (!defaultTranslation) {
+        throw new AstroError(
+            `The ${description} for "${link}" must have a key for the default language "${defaultLang}".`,
+            'Update the Starlight config to include a topic label for the default language.'
+        );
+    }
+
+    let translation = defaultTranslation;
+
+    if (Astro.currentLocale) {
+        translation = translations[Astro.currentLocale] ?? defaultTranslation;
+    }
+
+    return translation;
+}
+---
+
+<nav class="nav-bar">
+    {
+        userConfig.navLinks?.map((nav) => {
+            const absoluteLinkRegex = /^https?:\/\//;
+
+            const link =
+                !absoluteLinkRegex.test(nav.link) && Astro.currentLocale
+                    ? getRelativeLocaleUrl(Astro.currentLocale, nav.link)
+                    : nav.link;
+            const label =
+                typeof nav.label === 'string'
+                    ? nav.label
+                    : getTranslation(nav.label, nav.link, 'label');
+
+            return (
+                <a class:list={[{ active: currentPath === link }]} href={link} {...nav.attrs}>
+                    {label}
+                    {nav.badge && <span class="badge">{nav.badge}</span>}
+                </a>
+            );
+        })
+    }
+</nav>
+
+<style>
+    .nav-bar {
+        font-size: 0.875rem;
+        line-height: 1.25rem;
+        align-items: center;
+        display: flex;
+    }
+
+    @media (min-width: 1280px) {
+        .nav-bar {
+            gap: 0.375rem;
+        }
+    }
+
+    .nav-bar a {
+        display: inline-flex;
+        align-items: center;
+        justify-content: center;
+        font-weight: 500;
+        min-height: 2rem;
+        padding: 0 0.625rem;
+        border-radius: calc(var(--radius) - 2px);
+        text-decoration: none;
+        transition-property:
+            color, background-color, border-color, text-decoration-color, fill, stroke;
+        transition-timing-function: cubic-bezier(0.4, 0, 0.2, 1);
+        transition-duration: 0.15s;
+        color: var(--foreground);
+    }
+
+    .nav-bar a:hover {
+        color: var(--accent-foreground);
+        background-color: color-mix(in oklab, var(--accent) 80%, transparent);
+    }
+
+    .badge {
+        padding-top: calc(var(--spacing) * 0.5);
+        padding-bottom: calc(var(--spacing) * 0.5);
+        padding-left: calc(var(--spacing) * 1.5);
+        padding-right: calc(var(--spacing) * 1.5);
+        margin-left: calc(var(--spacing) * 2);
+        border-radius: 0.375rem;
+        font-size: 0.75rem;
+        line-height: 1rem;
+        font-weight: 400;
+        line-height: 1;
+        text-decoration: none;
+        background: #adfa1d;
+        color: #000000;
+    }
+</style>

package/components/overrides/parts/SidebarSublist.astro

@@ -0,0 +1,115 @@
+---
+import type { StarlightRouteData } from '@astrojs/starlight/route-data';
+
+interface Props {
+    sublist: StarlightRouteData['sidebar'];
+    nested?: boolean;
+}
+
+const { sublist } = Astro.props;
+---
+
+{
+    sublist.map((entry) =>
+        entry.type === 'link' ? (
+            <a
+                href={entry.href}
+                aria-current={entry.isCurrent && 'page'}
+                class:list={['entry-link', entry.attrs.class]}
+                {...entry.attrs}
+            >
+                <span class="entry-link-inner">
+                    {entry.label}
+                    {entry.badge && <span class="entry-badge">{entry.badge.text}</span>}
+                </span>
+            </a>
+        ) : (
+            <div class="container-sidebar-entry">
+                <h4 class="entry-title">{entry.label}</h4>
+                <div class="container-group-link">
+                    <Astro.self sublist={entry.entries} nested />
+                </div>
+            </div>
+        )
+    )
+}
+
+<style>
+    .container-sidebar-entry {
+        gap: 0.25rem;
+        flex-direction: column;
+        display: flex;
+    }
+
+    .entry-title {
+        font-weight: 600;
+        font-size: 0.75rem;
+        line-height: 1rem;
+        padding-top: calc(var(--spacing) * 1);
+        padding-bottom: calc(var(--spacing) * 1);
+        padding-left: calc(var(--spacing) * 2);
+        padding-right: calc(var(--spacing) * 2);
+        border-radius: calc(var(--radius) - 2px);
+        color: var(--muted-foreground);
+    }
+
+    .container-group-link {
+        font-size: 0.875rem;
+        line-height: 1.25rem;
+        gap: 2px;
+        grid-auto-rows: max-content;
+        grid-auto-flow: row;
+        display: grid;
+    }
+
+    .entry-link {
+        color: var(--foreground);
+        font-weight: 400;
+        align-items: center;
+        width: 100%;
+        height: 1.875rem;
+        display: flex;
+        text-decoration: none;
+        font-size: 0.8rem;
+        line-height: 1.125rem;
+    }
+
+    .entry-link-inner {
+        display: flex;
+        align-items: center;
+        padding-left: calc(var(--spacing) * 2);
+        padding-right: calc(var(--spacing) * 2);
+        border-radius: calc(var(--radius) - 2px);
+        height: 100%;
+        transition:
+            color 0.15s,
+            background-color 0.15s;
+    }
+
+    .entry-link[aria-current='page'] {
+        font-weight: 500;
+    }
+
+    .entry-link[aria-current='page'] .entry-link-inner {
+        background-color: var(--accent);
+        color: var(--accent-foreground);
+    }
+
+    .entry-link:hover:not([aria-current='page']) .entry-link-inner {
+        background-color: var(--secondary);
+        color: var(--secondary-foreground);
+    }
+
+    .entry-badge {
+        color: rgb(0 0 0);
+        line-height: 1;
+        font-size: 0.75rem;
+        padding-top: calc(var(--spacing) * 0.5);
+        padding-bottom: calc(var(--spacing) * 0.5);
+        padding-left: calc(var(--spacing) * 1.5);
+        padding-right: calc(var(--spacing) * 1.5);
+        background-color: rgb(173 250 29);
+        border-radius: calc(var(--radius) - 2px);
+        margin-left: calc(var(--spacing) * 2);
+    }
+</style>

package/components/overrides/parts/toc/TableOfContentsList.astro

@@ -0,0 +1,71 @@
+---
+import type { MarkdownHeading } from 'astro';
+
+interface TocItem extends MarkdownHeading {
+    children: TocItem[];
+}
+
+interface Props {
+    toc: TocItem[];
+    depth?: number;
+    isMobile?: boolean;
+}
+
+const { toc, depth = 0 } = Astro.props;
+---
+
+<ul>
+    {
+        toc.map((heading) => (
+            <li>
+                <a href={'#' + heading.slug}>{heading.text}</a>
+                {heading.children.length > 0 && (
+                    <Astro.self toc={heading.children} depth={depth + 1} />
+                )}
+            </li>
+        ))
+    }
+</ul>
+
+<style define:vars={{ depth }}>
+    ul {
+        list-style-type: none;
+        margin: 0;
+        padding: 0;
+    }
+    li {
+        line-height: 1;
+        padding-top: 0;
+        margin-top: 0;
+    }
+
+    li + li {
+        margin-top: calc(var(--spacing) * 2);
+    }
+
+    a {
+        text-decoration-line: none;
+        color: var(--muted-foreground);
+        display: inline-block;
+        text-decoration: inherit;
+        font-size: 0.8rem;
+        font-weight: 400;
+        line-height: 1.125rem;
+    }
+
+    a:hover {
+        color: color-mix(in oklab, var(--foreground) 72%, var(--muted-foreground));
+    }
+
+    a[aria-current] {
+        color: var(--foreground);
+        font-weight: 500;
+    }
+
+    ul > li > ul {
+        --pad-inline: calc(var(--spacing) * 2);
+        margin-top: calc(var(--spacing) * 2);
+        padding-inline: calc((1rem - var(--pad-inline)) / var(--depth) + var(--pad-inline))
+            var(--pad-inline);
+    }
+</style>

package/components/overrides/parts/toc/starlight-toc.ts

@@ -0,0 +1,119 @@
+/* eslint-disable ts/explicit-function-return-type */
+/* eslint-disable accessor-pairs */
+/* eslint-disable ts/strict-boolean-expressions */
+
+import { PAGE_TITLE_ID } from '../../../../core/config/constants';
+
+export class StarlightTOC extends HTMLElement {
+    private _current = this.querySelector<HTMLAnchorElement>('a[aria-current="true"]');
+    private minH = Number.parseInt(this.dataset.minH || '2', 10);
+    private maxH = Number.parseInt(this.dataset.maxH || '3', 10);
+
+    protected set current(link: HTMLAnchorElement) {
+        if (link === this._current) return;
+        if (this._current) this._current.removeAttribute('aria-current');
+        link.setAttribute('aria-current', 'true');
+        this._current = link;
+    }
+
+    private onIdle = (cb: IdleRequestCallback) =>
+        (window.requestIdleCallback || ((cb) => setTimeout(cb, 1)))(cb);
+
+    constructor() {
+        super();
+        this.onIdle(() => this.init());
+    }
+
+    private init = (): void => {
+        /** All the links in the table of contents. */
+        const links = [...this.querySelectorAll('a')];
+
+        /** Test if an element is a table-of-contents heading. */
+        const isHeading = (el: Element): el is HTMLHeadingElement => {
+            if (el instanceof HTMLHeadingElement) {
+                // Special case for page title h1
+                if (el.id === PAGE_TITLE_ID) return true;
+                // Check the heading level is within the user-configured limits for the ToC
+                const level = el.tagName[1];
+                if (level) {
+                    const int = Number.parseInt(level, 10);
+                    if (int >= this.minH && int <= this.maxH) return true;
+                }
+            }
+            return false;
+        };
+
+        /** Walk up the DOM to find the nearest heading. */
+        const getElementHeading = (el: Element | null): HTMLHeadingElement | null => {
+            if (!el) return null;
+            const origin = el;
+            while (el) {
+                if (isHeading(el)) return el;
+                // Assign the previous sibling’s last, most deeply nested child to el.
+                el = el.previousElementSibling;
+                while (el?.lastElementChild) {
+                    el = el.lastElementChild;
+                }
+                // Look for headings amongst siblings.
+                const h = getElementHeading(el);
+                if (h) return h;
+            }
+            // Walk back up the parent.
+            return getElementHeading(origin.parentElement);
+        };
+
+        /** Handle intersections and set the current link to the heading for the current intersection. */
+        const setCurrent: IntersectionObserverCallback = (entries) => {
+            for (const { isIntersecting, target } of entries) {
+                if (!isIntersecting) continue;
+                const heading = getElementHeading(target);
+                if (!heading) continue;
+                const link = links.find(
+                    (link) => link.hash === `#${encodeURIComponent(heading.id)}`
+                );
+                if (link) {
+                    this.current = link;
+                    break;
+                }
+            }
+        };
+
+        // Observe elements with an `id` (most likely headings) and their siblings.
+        // Also observe direct children of `.content` to include elements before
+        // the first heading.
+        const toObserve = document.querySelectorAll('main [id], main [id] ~ *, main .content > *');
+
+        let observer: IntersectionObserver | undefined;
+        const observe = () => {
+            if (observer) return;
+            observer = new IntersectionObserver(setCurrent, { rootMargin: this.getRootMargin() });
+            toObserve.forEach((h) => observer!.observe(h));
+        };
+        observe();
+
+        let timeout: NodeJS.Timeout;
+        window.addEventListener('resize', () => {
+            // Disable intersection observer while window is resizing.
+            if (observer) {
+                observer.disconnect();
+                observer = undefined;
+            }
+            clearTimeout(timeout);
+            timeout = setTimeout(() => this.onIdle(observe), 200);
+        });
+    };
+
+    private getRootMargin(): `-${number}px 0% ${number}px` {
+        const navBarHeight = document.querySelector('header')?.getBoundingClientRect().height || 0;
+        // `<summary>` only exists in mobile ToC, so will fall back to 0 in large viewport component.
+        const mobileTocHeight = this.querySelector('summary')?.getBoundingClientRect().height || 0;
+        /** Start intersections at nav height + 2rem padding. */
+        const top = navBarHeight + mobileTocHeight + 32;
+        /** End intersections `53px` later. This is slightly more than the maximum `margin-top` in Markdown content. */
+        const bottom = top + 53;
+        const height = document.documentElement.clientHeight;
+        return `-${top}px 0% ${bottom - height}px`;
+    }
+}
+
+customElements.define('starlight-toc', StarlightTOC);

package/core/config/constants.ts

@@ -0,0 +1 @@
+export const PAGE_TITLE_ID = '_top';

package/core/config/expresive-code.ts

@@ -0,0 +1,63 @@
+import type { StarlightExpressiveCodeOptions } from '@astrojs/starlight/expressive-code';
+import type { StarlightUserConfig } from '@astrojs/starlight/types';
+
+const createInlineSvgUrl = (svgContents: string): string => {
+    const inlineSvg = svgContents.replace(
+        /^(\s*<svg)\s+([^>]+)\s*(\/?>)/,
+        (_match, tagStart: string, attributes: string, tagEnd: string) => {
+            const sanitizedAttributes = attributes.replaceAll(
+                /(?:width|height)\s*=\s*(?:(["'])[^"']*\1|\d+)\s*/g,
+                ''
+            );
+
+            return `${tagStart} ${sanitizedAttributes.trim()}${tagEnd}`;
+        }
+    );
+
+    return `url("data:image/svg+xml,${encodeURIComponent(inlineSvg)}")`;
+};
+
+export const expressiveCode = (
+    config: StarlightUserConfig
+): boolean | StarlightExpressiveCodeOptions => {
+    const userExpressiveCodeConfig =
+        config.expressiveCode === false || config.expressiveCode === true
+            ? {}
+            : config.expressiveCode;
+
+    return config.expressiveCode === false
+        ? false
+        : {
+              themes: ['github-dark-default', 'github-light-default'],
+              ...userExpressiveCodeConfig,
+              styleOverrides: {
+                  codeBackground: 'var(--code-background)',
+                  borderWidth: '0px',
+                  borderRadius: 'calc(var(--radius) + 4px)',
+                  gutterBorderWidth: '0px',
+                  ...userExpressiveCodeConfig?.styleOverrides,
+                  frames: {
+                      editorBackground: 'var(--code-background)',
+                      editorActiveTabBackground: 'var(--gray-5)',
+                      editorActiveTabForeground: 'var(--foreground)',
+                      editorTabBarBackground: 'var(--gray-6)',
+                      editorTabBarBorderColor: 'var(--border)',
+                      editorTabBarBorderBottomColor: 'var(--border)',
+                      terminalBackground: 'var(--code-background)',
+                      terminalTitlebarBackground: 'var(--gray-6)',
+                      terminalTitlebarBorderBottomColor: 'var(--border)',
+                      terminalTitlebarForeground: 'var(--muted-foreground)',
+                      shadowColor: 'transparent',
+                      copyIcon: createInlineSvgUrl(
+                          `<svg xmlns="http://www.w3.org/2000/svg" width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-clipboard"><rect width="8" height="4" x="8" y="2" rx="1" ry="1"></rect><path d="M16 4h2a2 2 0 0 1 2 2v14a2 2 0 0 1-2 2H6a2 2 0 0 1-2-2V6a2 2 0 0 1 2-2h2"></path></svg>`
+                      ),
+                      ...userExpressiveCodeConfig?.styleOverrides?.frames,
+                  },
+                  textMarkers: {
+                      markBackground: 'var(--mark-background)',
+                      markBorderColor: 'var(--border)',
+                      ...userExpressiveCodeConfig?.styleOverrides?.textMarkers,
+                  },
+              },
+          };
+};

package/core/config/override.ts

@@ -0,0 +1,48 @@
+import type { HookParameters } from '@astrojs/starlight/types';
+import type { AstroIntegrationLogger } from 'astro';
+
+type StarlightUserConfig = HookParameters<'config:setup'>['config'];
+type ComponentOverride = keyof NonNullable<StarlightUserConfig['components']>;
+
+export const COMPONENT_OVERRIDES: ComponentOverride[] = [
+    'ThemeSelect',
+    'PageFrame',
+    'Header',
+    'SiteTitle',
+    'Sidebar',
+    'TwoColumnContent',
+    'ContentPanel',
+    'PageTitle',
+    'MarkdownContent',
+    'Hero',
+    'Footer',
+    'SocialIcons',
+    'Pagination',
+    'Search',
+    'TableOfContents',
+    'PageSidebar',
+];
+
+export function override(
+    starlightConfig: StarlightUserConfig,
+    overrides: ComponentOverride[],
+    logger: AstroIntegrationLogger
+): StarlightUserConfig['components'] {
+    const components = { ...starlightConfig.components };
+    for (const override of overrides) {
+        if (starlightConfig.components?.[override] != null) {
+            const fallback = `lucode-starlight/components/overrides/${override}.astro`;
+
+            logger.warn(
+                `A \`<${override}>\` component override is already defined in your Starlight configuration.`
+            );
+            logger.warn(
+                `To use \`lucode-starlight/components\`, either remove this override or manually render the content from \`${fallback}\`.`
+            );
+            continue;
+        }
+        components[override] = `lucode-starlight/components/overrides/${override}.astro`;
+    }
+
+    return components;
+}

package/core/config/schemas.ts

@@ -0,0 +1,57 @@
+import type { AstroBuiltinAttributes } from 'astro';
+import type { HTMLAttributes } from 'astro/types';
+import { z } from 'astro/zod';
+
+const linkHTMLAttributesSchema = z.record(
+    z.string(),
+    z.union([z.string(), z.number(), z.boolean(), z.undefined()])
+) as z.Schema<Omit<HTMLAttributes<'a'>, keyof AstroBuiltinAttributes | 'children'>>;
+
+const LinkItemHTMLAttributesSchema = () => linkHTMLAttributesSchema.default({});
+
+export const linkSchema = z.object({
+    /**
+     * An optional badge to display next to the topic label.
+     *
+     * This option accepts the same configuration as the Starlight badge sidebar item configuration.
+     * @see https://starlight.astro.build/guides/sidebar/#badges
+     */
+    badge: z.string().optional(),
+    /**
+     * The topic label visible at the top of the sidebar.
+     *
+     * The value can be a string, or for multilingual sites, an object with values for each different locale. When using
+     * the object form, the keys must be BCP-47 tags (e.g. en, fr, or zh-CN).
+     */
+    label: z.union([z.string(), z.record(z.string(), z.string())]),
+    /**
+     * The link to the topic’s content which an be a relative link to local files or the full URL of an external page.
+     *
+     * For internal links, the link can either be a page included in the items array or a different page acting as the
+     * topic’s landing page.
+     */
+    link: z.string(),
+    /** HTML attributes to add to the link item. */
+    attrs: LinkItemHTMLAttributesSchema().optional(),
+});
+
+export type Link = z.infer<typeof linkSchema>;
+
+export const LucodeStarlightConfigSchema = z.object({
+    navLinks: z.array(linkSchema).optional(),
+    docs: z
+        .object({
+            includeAiUtilities: z.boolean().optional().default(false),
+        })
+        .optional()
+        .default({ includeAiUtilities: false }),
+    footerText: z
+        .string()
+        .optional()
+        .default(
+            'Inspired by the [shadcn/ui](https://ui.shadcn.com/) documentation theme and based on [starlight-theme-black](https://github.com/adrian-ub/starlight-theme-black). Ported to Astro Starlight by [lucas-labs](https://github.com/lucas-labs).'
+        ),
+});
+
+export type LucodeStarlightUserConfig = z.input<typeof LucodeStarlightConfigSchema>;
+export type LucodeStarlightConfig = z.output<typeof LucodeStarlightConfigSchema>;

package/core/config/vite.ts

@@ -0,0 +1,20 @@
+import type { ViteUserConfig } from 'astro';
+import type { LucodeStarlightConfig } from './schemas';
+
+export function vitePlugin(config: LucodeStarlightConfig): VitePlugin {
+    const moduleId = 'virtual:lucode-starlight-config';
+    const resolvedModuleId = `\0${moduleId}`;
+    const moduleContent = `export default ${JSON.stringify(config)}`;
+
+    return {
+        name: 'vite-plugin-lucode-starlight',
+        load(id) {
+            return id === resolvedModuleId ? moduleContent : undefined;
+        },
+        resolveId(id) {
+            return id === moduleId ? resolvedModuleId : undefined;
+        },
+    };
+}
+
+type VitePlugin = NonNullable<ViteUserConfig['plugins']>[number];

package/core/plugin.ts

@@ -0,0 +1,56 @@
+import type { StarlightPlugin } from '@astrojs/starlight/types';
+import { override, COMPONENT_OVERRIDES } from './config/override';
+import { expressiveCode } from './config/expresive-code';
+import { vitePlugin } from './config/vite';
+import {
+    LucodeStarlightConfigSchema,
+    type LucodeStarlightConfig,
+    type LucodeStarlightUserConfig,
+} from './config/schemas';
+
+const parseConfig = (userConfig?: LucodeStarlightUserConfig): LucodeStarlightConfig => {
+    const parsedConfig = LucodeStarlightConfigSchema.safeParse(userConfig ?? {});
+
+    if (!parsedConfig.success) {
+        throw new Error(
+            `The provided plugin configuration for lucode-starlight is invalid.\n${parsedConfig.error.issues.map((issue) => issue.message).join('\n')}`
+        );
+    }
+
+    return parsedConfig.data;
+};
+
+const plugin = (userConfig?: LucodeStarlightUserConfig): StarlightPlugin =>
+    ({
+        name: 'lucode-starlight',
+        hooks: {
+            'config:setup': ({ config, logger, updateConfig, addIntegration }) => {
+                updateConfig({
+                    components: override(config, COMPONENT_OVERRIDES, logger),
+                    customCss: [
+                        ...(config.customCss ?? []),
+                        'lucode-starlight/styles/layers',
+                        'lucode-starlight/styles/theme',
+                        'lucode-starlight/styles/base',
+                    ],
+                    expressiveCode: expressiveCode(config),
+                });
+
+                addIntegration({
+                    name: 'lucode-starlight-integration',
+                    hooks: {
+                        'astro:config:setup': ({ updateConfig }) => {
+                            updateConfig({
+                                vite: { plugins: [vitePlugin(parseConfig(userConfig))] },
+                            });
+                        },
+                    },
+                });
+            },
+            // 'i18n:setup': function ({ injectTranslations }) {
+            //     injectTranslations(translations);
+            // },
+        },
+    }) satisfies StarlightPlugin;
+
+export { plugin };

package/global.d.ts

@@ -0,0 +1,5 @@
+export declare global {
+    var StarlightThemeProvider: {
+        updatePickers(theme?: string): void;
+    };
+}

package/index.ts

@@ -0,0 +1,3 @@
+import { plugin } from './core/plugin';
+
+export default plugin;