@grove-dev/starlight 0.6.1 → 0.8.0

package/components/overrides/parts/NavBar.astro

@@ -1,36 +1,19 @@
 ---
-import { AstroError } from 'astro/errors';
-import userConfig from 'virtual:lucode-starlight-config';
-import starlightConfig from 'virtual:starlight/user-config';
 import { getRelativeLocaleUrl } from 'astro:i18n';
+import userConfig from 'virtual:grove-starlight-config';
+import starlightConfig from 'virtual:starlight/user-config';
+import { createLocaleLookup, resolveNavLabel } from '../../../core/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.'
-        );
-    }
+const { lang, locale } = Astro.locals.starlightRoute;
 
-    let translation = defaultTranslation;
-
-    if (Astro.currentLocale) {
-        translation = translations[Astro.currentLocale] ?? defaultTranslation;
-    }
-
-    return translation;
-}
+const localeKeys = createLocaleLookup({
+  lang,
+  locale: Astro.currentLocale ?? locale,
+  defaultLang: starlightConfig.defaultLocale?.lang,
+  defaultLocale: starlightConfig.defaultLocale?.locale,
+});
 ---
 
 <nav class="nav-bar">
@@ -42,10 +25,8 @@ export function getTranslation(
                 !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');
+
+            const label = resolveNavLabel(nav.label, nav.translations, localeKeys);
 
             return (
                 <a class:list={[{ active: currentPath === link }]} href={link} {...nav.attrs}>

package/components/overrides/parts/SidebarSublist.astro

@@ -1,12 +1,15 @@
 ---
+import { Icon } from '@astrojs/starlight/components';
+import SidebarRestorePoint from '@astrojs/starlight/components/SidebarRestorePoint.astro';
 import type { StarlightRouteData } from '@astrojs/starlight/route-data';
+import { isSidebarGroupOpen } from '../../../core/sidebar';
 
 interface Props {
-    sublist: StarlightRouteData['sidebar'];
-    nested?: boolean;
+  sublist: StarlightRouteData['sidebar'];
+  nested?: boolean;
 }
 
-const { sublist } = Astro.props;
+const { sublist, nested = false } = Astro.props;
 ---
 
 {
@@ -14,7 +17,7 @@ const { sublist } = Astro.props;
         entry.type === 'link' ? (
             <a
                 href={entry.href}
-                aria-current={entry.isCurrent && 'page'}
+                aria-current={entry.isCurrent ? 'page' : undefined}
                 class:list={['entry-link', entry.attrs.class]}
                 {...entry.attrs}
             >
@@ -23,6 +26,20 @@ const { sublist } = Astro.props;
                     {entry.badge && <span class="entry-badge">{entry.badge.text}</span>}
                 </span>
             </a>
+        ) : nested ? (
+            <details class="entry-group" open={isSidebarGroupOpen(entry)}>
+                <summary class="entry-group-summary">
+                    <span class="entry-link-inner">
+                        {entry.label}
+                        {entry.badge && <span class="entry-badge">{entry.badge.text}</span>}
+                    </span>
+                    <Icon name="right-caret" class="entry-group-caret" size="1rem" />
+                </summary>
+                <SidebarRestorePoint />
+                <div class="container-group-link nested">
+                    <Astro.self sublist={entry.entries} nested />
+                </div>
+            </details>
         ) : (
             <div class="container-sidebar-entry">
                 <h4 class="entry-title">{entry.label}</h4>
@@ -62,6 +79,60 @@ const { sublist } = Astro.props;
         display: grid;
     }
 
+    /*
+     * Nested levels are indented with a guide line rather than plain padding, so that a reader can
+     * follow which group a link belongs to once the tree is more than one level deep.
+     */
+    .container-group-link.nested {
+        margin-left: calc(var(--spacing) * 2);
+        padding-left: calc(var(--spacing) * 2);
+        border-left: 1px solid var(--border);
+    }
+
+    .entry-group {
+        display: flex;
+        flex-direction: column;
+        gap: 2px;
+    }
+
+    .entry-group-summary {
+        display: flex;
+        align-items: center;
+        justify-content: space-between;
+        gap: calc(var(--spacing) * 1);
+        height: 1.875rem;
+        cursor: pointer;
+        list-style: none;
+        color: var(--foreground);
+        font-size: 0.8rem;
+        line-height: 1.125rem;
+        border-radius: calc(var(--radius) - 2px);
+        transition:
+            color 0.15s,
+            background-color 0.15s;
+    }
+
+    /* Safari still paints its own marker without this. */
+    .entry-group-summary::-webkit-details-marker {
+        display: none;
+    }
+
+    .entry-group-summary:hover {
+        background-color: var(--secondary);
+        color: var(--secondary-foreground);
+    }
+
+    .entry-group-caret {
+        flex-shrink: 0;
+        margin-right: calc(var(--spacing) * 2);
+        color: var(--muted-foreground);
+        transition: transform 0.15s;
+    }
+
+    .entry-group[open] > .entry-group-summary .entry-group-caret {
+        transform: rotate(90deg);
+    }
+
     .entry-link {
         color: var(--foreground);
         font-weight: 400;

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

@@ -2,13 +2,13 @@
 import type { MarkdownHeading } from 'astro';
 
 interface TocItem extends MarkdownHeading {
-    children: TocItem[];
+  children: TocItem[];
 }
 
 interface Props {
-    toc: TocItem[];
-    depth?: number;
-    isMobile?: boolean;
+  toc: TocItem[];
+  depth?: number;
+  isMobile?: boolean;
 }
 
 const { toc, depth = 0 } = Astro.props;

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

@@ -5,115 +5,113 @@
 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);
+  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;
-    }
+  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);
+  private onIdle = (cb: IdleRequestCallback) =>
+    (window.requestIdleCallback || ((cb) => setTimeout(cb, 1)))(cb);
 
-    constructor() {
-        super();
-        this.onIdle(() => this.init());
-    }
+  constructor() {
+    super();
+    this.onIdle(() => this.init());
+  }
 
-    private init = (): void => {
-        /** All the links in the table of contents. */
-        const links = [...this.querySelectorAll('a')];
+  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);
-        };
+    /** 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;
+    };
 
-        /** 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;
-                }
-            }
-        };
+    /** 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);
+    };
 
-        // 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 > *');
+    /** 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;
+        }
+      }
+    };
 
-        let observer: IntersectionObserver | undefined;
-        const observe = () => {
-            if (observer) return;
-            observer = new IntersectionObserver(setCurrent, { rootMargin: this.getRootMargin() });
-            toObserve.forEach((h) => observer!.observe(h));
-        };
-        observe();
+    // 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 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);
-        });
+    let observer: IntersectionObserver | undefined;
+    const observe = () => {
+      if (observer) return;
+      observer = new IntersectionObserver(setCurrent, { rootMargin: this.getRootMargin() });
+      for (const h of toObserve) 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`;
-    }
+  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/docs-schema.ts

@@ -0,0 +1,58 @@
+/**
+ * Starlight validates frontmatter with `z.object`, which strips keys it does not know about. When
+ * `docsSchema()` is called without `extend: ExtendDocsSchema`, the theme's own `hero` fields are
+ * therefore dropped without any error, and splash pages silently fall back to the default layout.
+ *
+ * Detecting that from the parsed frontmatter is unreliable: Starlight builds some entries in code
+ * rather than through the schema — its fallback 404 route hardcodes `hero` — so those look stripped
+ * even on a correctly configured site. Instead, `@grove-dev/starlight/schema` records that it was
+ * imported, which answers the actual question: did the user wire the extension up at all?
+ */
+const LOADED = Symbol.for('@grove-dev/starlight.docs-schema-loaded');
+
+/** Called by `@grove-dev/starlight/schema` on import. */
+export function markDocsSchemaLoaded(): void {
+  (globalThis as Record<symbol, unknown>)[LOADED] = true;
+}
+
+export function isDocsSchemaExtended(): boolean {
+  return (globalThis as Record<symbol, unknown>)[LOADED] === true;
+}
+
+let warned = false;
+
+/**
+ * Emits {@link missingDocsSchemaWarning} the first time a page with a hero is rendered on a site
+ * that never imported the schema. Returns whether it warned; later calls are no-ops, so a site with
+ * several splash pages does not repeat the same advice once per page.
+ */
+export function warnAboutMissingDocsSchemaOnce(
+  hero: unknown,
+  warn: (message: string) => void = console.warn,
+): boolean {
+  if (warned || hero == null || isDocsSchemaExtended()) return false;
+
+  warned = true;
+  warn(missingDocsSchemaWarning());
+  return true;
+}
+
+/** Test seam: clears the once-per-process guard used by {@link warnAboutMissingDocsSchemaOnce}. */
+export function resetDocsSchemaWarning(): void {
+  warned = false;
+}
+
+/** The advice printed when the schema extension is missing. */
+export function missingDocsSchemaWarning(): string {
+  return [
+    '[@grove-dev/starlight] This page sets `hero` frontmatter, but the docs schema is not extended,',
+    "so Starlight is dropping the theme's hero fields. `hero.layout`, `hero.announcement` and the",
+    'extra `hero.actions[].variant` values have no effect until you extend it:',
+    '',
+    "    import { ExtendDocsSchema } from '@grove-dev/starlight/schema';",
+    '',
+    '    schema: docsSchema({ extend: ExtendDocsSchema }),',
+    '',
+    'See https://withgrove.dev/reference/plugin-api/#frontmatter-extension',
+  ].join('\n');
+}

package/core/config/expresive-code.ts

@@ -2,62 +2,60 @@ import type { StarlightExpressiveCodeOptions } from '@astrojs/starlight/expressi
 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,
-                ''
-            );
+  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 `${tagStart} ${sanitizedAttributes.trim()}${tagEnd}`;
+    },
+  );
 
-    return `url("data:image/svg+xml,${encodeURIComponent(inlineSvg)}")`;
+  return `url("data:image/svg+xml,${encodeURIComponent(inlineSvg)}")`;
 };
 
 export const expressiveCode = (
-    config: StarlightUserConfig
+  config: StarlightUserConfig,
 ): boolean | StarlightExpressiveCodeOptions => {
-    const userExpressiveCodeConfig =
-        config.expressiveCode === false || config.expressiveCode === true
-            ? {}
-            : config.expressiveCode;
+  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,
-                  },
-              },
-          };
+  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,
+          },
+        },
+      };
 };