@grove-dev/starlight 0.6.1 → 0.8.0

package/components/custom/dropdown/DropdownContent.astro

@@ -2,35 +2,35 @@
 import type { HTMLAttributes } from 'astro/types';
 
 type Props = HTMLAttributes<'div'> & {
-    /**
-     * Side of the dropdown
-     * @default bottom
-     */
-    side?: 'top' | 'bottom' | 'left' | 'right';
-    /**
-     * Alignment of the dropdown
-     * @default start
-     */
-    align?: 'start' | 'center' | 'end';
-    /**
-     * Offset distance in pixels
-     * @default 4
-     */
-    sideOffset?: number;
-    /**
-     * Open and close animation duration in milliseconds
-     * @default 150
-     */
-    animationDuration?: number;
+  /**
+   * Side of the dropdown
+   * @default bottom
+   */
+  side?: 'top' | 'bottom' | 'left' | 'right';
+  /**
+   * Alignment of the dropdown
+   * @default start
+   */
+  align?: 'start' | 'center' | 'end';
+  /**
+   * Offset distance in pixels
+   * @default 4
+   */
+  sideOffset?: number;
+  /**
+   * Open and close animation duration in milliseconds
+   * @default 150
+   */
+  animationDuration?: number;
 };
 
 const {
-    class: className,
-    side = 'bottom',
-    align = 'start',
-    sideOffset = 4,
-    animationDuration = 150,
-    ...rest
+  class: className,
+  side = 'bottom',
+  align = 'start',
+  sideOffset = 4,
+  animationDuration = 150,
+  ...rest
 } = Astro.props;
 ---
 
@@ -59,7 +59,7 @@ const {
 <style>
     div[data-slot='dropdown-content'] {
         background-color: var(--popover-background, var(--muted));
-        color: var(var(--popover-foreground), var(--foreground));
+        color: var(--popover-foreground, var(--foreground));
         z-index: 50;
         min-width: 9rem;
         overflow-x: hidden;
@@ -134,46 +134,46 @@ const {
         &[data-side='right'][data-align='end'] {
             bottom: 0;
         }
+    }
+
+    /* animations */
+    @keyframes fade-in {
+        from {
+            opacity: 0;
+        }
+        to {
+            opacity: 1;
+        }
+    }
+
+    @keyframes fade-out {
+        from {
+            opacity: 1;
+        }
+        to {
+            opacity: 0;
+        }
+    }
 
-        /* animations */
-        @keyframes fade-in {
-            from {
-                opacity: 0;
-            }
-            to {
-                opacity: 1;
-            }
-        }
-
-        @keyframes fade-out {
-            from {
-                opacity: 1;
-            }
-            to {
-                opacity: 0;
-            }
-        }
-
-        @keyframes zoom-in-95 {
-            from {
-                opacity: 0;
-                transform: scale(0.95);
-            }
-            to {
-                opacity: 1;
-                transform: scale(1);
-            }
-        }
-
-        @keyframes zoom-out-95 {
-            from {
-                opacity: 1;
-                transform: scale(1);
-            }
-            to {
-                opacity: 0;
-                transform: scale(0.95);
-            }
+    @keyframes zoom-in-95 {
+        from {
+            opacity: 0;
+            transform: scale(0.95);
+        }
+        to {
+            opacity: 1;
+            transform: scale(1);
+        }
+    }
+
+    @keyframes zoom-out-95 {
+        from {
+            opacity: 1;
+            transform: scale(1);
+        }
+        to {
+            opacity: 0;
+            transform: scale(0.95);
         }
     }
 </style>

package/components/custom/dropdown/DropdownItem.astro

@@ -2,14 +2,14 @@
 import type { HTMLTag, Polymorphic } from 'astro/types';
 
 type Props<Tag extends HTMLTag> = Polymorphic<{ as: Tag }> & {
-    /**
-     * Whether the item is inset (has left padding)
-     */
-    inset?: boolean;
-    /**
-     * Whether the item is disabled
-     */
-    disabled?: boolean;
+  /**
+   * Whether the item is inset (has left padding)
+   */
+  inset?: boolean;
+  /**
+   * Whether the item is disabled
+   */
+  disabled?: boolean;
 };
 
 const { class: className, inset = false, disabled = false, as: Tag = 'div', ...rest } = Astro.props;
@@ -53,7 +53,12 @@ const { class: className, inset = false, disabled = false, as: Tag = 'div', ...r
             color: var(--accent-foreground);
         }
 
-        > svg {
+        /*
+         * `:global` because the icon is slotted in by the consumer, so it carries that component's
+         * scope class rather than this one's. Astro 7 scopes descendant selectors that Astro 6 left
+         * alone, which would otherwise leave slotted icons unsized.
+         */
+        > :global(svg) {
             width: 1rem;
             height: 1rem;
             flex-shrink: 0;

package/components/custom/dropdown/DropdownLabel.astro

@@ -2,10 +2,10 @@
 import type { HTMLAttributes } from 'astro/types';
 
 type Props = HTMLAttributes<'div'> & {
-    /**
-     * Whether the label is inset (has left padding)
-     */
-    inset?: boolean;
+  /**
+   * Whether the label is inset (has left padding)
+   */
+  inset?: boolean;
 };
 
 const { class: className, inset = false, ...rest } = Astro.props;

package/components/custom/dropdown/DropdownTrigger.astro

@@ -1,29 +1,29 @@
 ---
 import type { HTMLAttributes } from 'astro/types';
-import LinkButton from '../LinkButton.astro';
+import LinkButton, { type ButtonVariant, type LegacyButtonVariant } from '../LinkButton.astro';
 
 type Props = Omit<HTMLAttributes<'button'>, 'role' | 'type'> & {
-    /**
-     * When true, the component will render its child element with a simple wrapper instead of a button component
-     */
-    asChild?: boolean;
+  /**
+   * When true, the component will render its child element with a simple wrapper instead of a button component
+   */
+  asChild?: boolean;
 
-    variant?: 'primary' | 'secondary' | 'minimal';
-    size?: '2xs' | 'xs' | 'sm' | 'md' | 'lg' | 'icon-sm' | 'icon-md' | 'icon-lg';
+  variant?: ButtonVariant | LegacyButtonVariant;
+  size?: '2xs' | 'xs' | 'sm' | 'md' | 'lg' | 'icon-sm' | 'icon-md' | 'icon-lg';
 };
 
 const {
-    class: className,
-    variant = 'secondary',
-    size = 'sm',
-    asChild = false,
-    ...rest
+  class: className,
+  variant = 'secondary',
+  size = 'sm',
+  asChild = false,
+  ...rest
 } = Astro.props;
 
 // Get the first child element if asChild is true
 let hasChildren = false;
 if (Astro.slots.has('default')) {
-    hasChildren = true;
+  hasChildren = true;
 }
 ---
 

package/components/custom/dropdown/index.ts

@@ -9,21 +9,21 @@ import DropdownShortcut from './DropdownShortcut.astro';
 import DropdownTrigger from './DropdownTrigger.astro';
 
 export {
-    Dropdown,
-    DropdownContent,
-    DropdownItem,
-    DropdownLabel,
-    DropdownSeparator,
-    DropdownShortcut,
-    DropdownTrigger,
+  Dropdown,
+  DropdownContent,
+  DropdownItem,
+  DropdownLabel,
+  DropdownSeparator,
+  DropdownShortcut,
+  DropdownTrigger,
 };
 
 export default {
-    Root: Dropdown,
-    Trigger: DropdownTrigger,
-    Content: DropdownContent,
-    Item: DropdownItem,
-    Label: DropdownLabel,
-    Separator: DropdownSeparator,
-    Shortcut: DropdownShortcut,
+  Root: Dropdown,
+  Trigger: DropdownTrigger,
+  Content: DropdownContent,
+  Item: DropdownItem,
+  Label: DropdownLabel,
+  Separator: DropdownSeparator,
+  Shortcut: DropdownShortcut,
 };

package/components/overrides/Footer.astro

@@ -5,9 +5,9 @@ import Pagination from 'virtual:starlight/components/Pagination';
 import config from 'virtual:starlight/user-config';
 
 const {
-    entry: {
-        data: { template },
-    },
+  entry: {
+    data: { template },
+  },
 } = Astro.locals.starlightRoute;
 
 const { lastUpdated: showLastUpdated, editLink } = config;

package/components/overrides/Header.astro

@@ -1,17 +1,16 @@
 ---
 import config from 'virtual:starlight/user-config';
+import LanguageSelect from '@astrojs/starlight/components/LanguageSelect.astro';
+import MobileMenuToggle from './parts/MobileMenuToggle.astro';
+import NavBar from './parts/NavBar.astro';
 import Search from './Search.astro';
+import SiteTitle from './SiteTitle.astro';
 import SocialIcons from './SocialIcons.astro';
-import LanguageSelect from '@astrojs/starlight/components/LanguageSelect.astro';
-
 import ThemeSelect from './ThemeSelect.astro';
-import SiteTitle from './SiteTitle.astro';
-import NavBar from './parts/NavBar.astro';
-import MobileMenuToggle from './parts/MobileMenuToggle.astro';
 
 /** render the `Search` component if Pagefind is enabled or the default search component has been overridden. */
 const shouldRenderSearch =
-    config.pagefind || config.components.Search !== '@astrojs/starlight/components/Search.astro';
+  config.pagefind || config.components.Search !== '@astrojs/starlight/components/Search.astro';
 ---
 
 <MobileMenuToggle />

package/components/overrides/Hero.astro

@@ -1,19 +1,27 @@
 ---
-import { Icon } from '@astrojs/starlight/components';
 import { Image } from 'astro:assets';
+import { Icon } from '@astrojs/starlight/components';
 import { PAGE_TITLE_ID } from '../../core/config/constants';
-import type { HeroLayout } from '../../schema';
+import { warnAboutMissingDocsSchemaOnce } from '../../core/config/docs-schema';
 import ContainerSection from '../custom/ContainerSection.astro';
 import LinkButton from '../custom/LinkButton.astro';
 
 const { data } = Astro.locals.starlightRoute.entry;
-const { title = data.title, tagline: heroTagline, image, actions = [] } = data.hero || {};
-const heroLayout = ((data.hero as any)?.layout as HeroLayout) ?? 'centered';
-const announcement =
-  ((data.hero as any)?.announcement as { text: string; link: string }) ?? undefined;
-const hasImage = !!image;
+
+warnAboutMissingDocsSchemaOnce(data.hero);
+
+const {
+  title = data.title,
+  tagline: heroTagline,
+  image,
+  announcement,
+  actions = [],
+} = data.hero || {};
+
+// Falls back on an empty tagline too, not just a missing one.
 const tagline = heroTagline || data.description;
 
+const hasImage = !!image;
 const imageAttrs = {
   loading: 'eager' as const,
   decoding: 'async' as const,
@@ -37,7 +45,7 @@ if (image) {
 ---
 
 <ContainerSection>
-    <div class="hero" data-layout={heroLayout} data-has-image={hasImage ? '' : undefined}>
+    <div class="hero" data-layout={data.hero?.layout} data-has-image={hasImage ? '' : undefined}>
         {
             hasImage && (
                 <div class="hero-image">
@@ -67,12 +75,11 @@ if (image) {
                     )
                 }
 
-                <h1 id={PAGE_TITLE_ID} data-page-title>{title}</h1>
+                <h1 id={PAGE_TITLE_ID} data-page-title set:html={title} />
             </div>
 
             <div class="hero-content-container">
-                {tagline && <div class="tagline">{tagline}</div>}
-
+                {tagline && <div class="tagline" set:html={tagline} />}
                 {
                     actions.length > 0 && (
                         <div class="actions">
@@ -91,7 +98,8 @@ if (image) {
                                         {...attrs}
                                     >
                                         {text}
-                                        {icon?.html && <Fragment set:html={icon.html} />}
+                                        {icon?.type === 'icon' && <Icon name={icon.name} />}
+                                        {icon?.type === 'raw' && <Fragment set:html={icon.html} />}
                                     </LinkButton>
                                 )
                             )}

package/components/overrides/PageFrame.astro

@@ -1,14 +1,30 @@
 ---
-import userConfig from 'virtual:lucode-starlight-config';
+import userConfig from 'virtual:grove-starlight-config';
+import starlightConfig from 'virtual:starlight/user-config';
+import { AstroError } from 'astro/errors';
+import { marked } from 'marked';
+import { createLocaleLookup, resolveLocalizedString } from '../../core/i18n';
 import Drawer from './parts/Drawer.astro';
 
-const { hasSidebar } = Astro.locals.starlightRoute;
-
-// `footerText` is a plain string from the consumer's `astro.config.mjs`.
-// Astro auto-escapes interpolated text, so emitting it directly is safe
-// and avoids the XSS sink that `marked.parseInline` + `set:html` would
-// create. Consumers who want rich formatting should render Markdown in
-// their own component instead of leaning on this slot.
+const { hasSidebar, lang, locale } = Astro.locals.starlightRoute;
+
+const localeKeys = createLocaleLookup({
+  lang,
+  locale: Astro.currentLocale ?? locale,
+  defaultLang: starlightConfig.defaultLocale?.lang,
+  defaultLocale: starlightConfig.defaultLocale?.locale,
+});
+
+let footerText: string;
+
+try {
+  footerText = resolveLocalizedString(userConfig.footerText, localeKeys);
+} catch (error) {
+  throw new AstroError(
+    error instanceof Error ? error.message : 'Invalid footerText localization.',
+    'Update the Grove config so footerText includes a key for the default language.',
+  );
+}
 ---
 
 <div data-slot="layout">
@@ -39,7 +55,7 @@ const { hasSidebar } = Astro.locals.starlightRoute;
     </main>
 
     <footer>
-        <div data-slot="footer-text">{userConfig.footerText}</div>
+        <div data-slot="footer-text" set:html={marked.parseInline(footerText)} />
     </footer>
 </div>
 

package/components/overrides/PageSidebar.astro

@@ -16,5 +16,6 @@ import TableOfContents from './TableOfContents.astro';
         max-height: calc(100vh - var(--header-height) - 1px);
         top: calc(var(--header-height) + 1px);
         position: sticky;
+        overflow-y: auto;
     }
 </style>

package/components/overrides/PageTitle.astro

@@ -1,13 +1,13 @@
 ---
+import userConfig from 'virtual:grove-starlight-config';
 import { Icon } from '@astrojs/starlight/components';
 import { PAGE_TITLE_ID } from '../../core/config/constants';
-import userConfig from 'virtual:lucode-starlight-config';
 import { Dropdown, DropdownContent, DropdownItem, DropdownTrigger } from '../custom/dropdown';
 import LinkButton from '../custom/LinkButton.astro';
 
 const {
-    entry: { data },
-    pagination: { prev, next },
+  entry: { data },
+  pagination: { prev, next },
 } = Astro.locals.starlightRoute;
 
 const { title, description } = data;

package/components/overrides/Search.astro

@@ -3,12 +3,12 @@ import '@pagefind/default-ui/css/ui.css';
 import project from 'virtual:starlight/project-context';
 
 const pagefindTranslations = {
-    placeholder: Astro.locals.t('search.label'),
-    ...Object.fromEntries(
-        Object.entries(Astro.locals.t.all())
-            .filter(([key]) => key.startsWith('pagefind.'))
-            .map(([key, value]) => [key.replace('pagefind.', ''), value])
-    ),
+  placeholder: Astro.locals.t('search.label'),
+  ...Object.fromEntries(
+    Object.entries(Astro.locals.t.all())
+      .filter(([key]) => key.startsWith('pagefind.'))
+      .map(([key, value]) => [key.replace('pagefind.', ''), value]),
+  ),
 };
 
 const dataAttributes: DOMStringMap = { 'data-translations': JSON.stringify(pagefindTranslations) };

package/components/overrides/Sidebar.astro

@@ -1,4 +1,5 @@
 ---
+import SidebarPersister from '@astrojs/starlight/components/SidebarPersister.astro';
 import SidebarSublist from './parts/SidebarSublist.astro';
 
 const { sidebar } = Astro.locals.starlightRoute;
@@ -10,12 +11,48 @@ const { sidebar } = Astro.locals.starlightRoute;
     <div class="sidebar-fade-top"></div>
     <div class="container-sidebar">
         <div class="sidebar-entries">
-            <SidebarSublist sublist={sidebar} />
+            {/* Keeps collapsed groups open and the scroll position across navigations. */}
+            <SidebarPersister>
+                <SidebarSublist sublist={sidebar} />
+            </SidebarPersister>
         </div>
         <div class="sidebar-fade-bottom"></div>
     </div>
 </div>
 
+{/*
+  Bring the current page's entry into view inside the sidebar's own scroll
+  container. SidebarPersister keeps the scroll position across navigations, but
+  on a fresh load (or the first visit to a deep page) the sidebar starts at the
+  top, so an entry far down the list renders off-screen with no hint that it is
+  selected. Only the container is scrolled -- never the page -- and only when
+  the entry is actually outside the visible band.
+*/}
+<script is:inline data-astro-rerun>
+    (() => {
+        const reveal = () => {
+            const container = document.querySelector('.container-sidebar');
+            const current = container?.querySelector('[aria-current="page"]');
+            if (!container || !current) return;
+
+            const view = container.getBoundingClientRect();
+            const entry = current.getBoundingClientRect();
+            if (entry.top >= view.top && entry.bottom <= view.bottom) return;
+
+            const offset =
+                entry.top - view.top - container.clientHeight / 2 + entry.height / 2;
+            // Instant, not smooth: this positions the sidebar for the page
+            // being loaded, so it should already be correct on first paint
+            // rather than animating into place while the reader looks at it.
+            container.scrollTop += offset;
+        };
+
+        // Runs after SidebarPersister has restored any stored scroll position.
+        requestAnimationFrame(reveal);
+        document.addEventListener('astro:page-load', () => requestAnimationFrame(reveal));
+    })();
+</script>
+
 <style>
     .sidebar {
         scrollbar-width: none;

package/components/overrides/SocialIcons.astro

@@ -32,7 +32,9 @@ const links = config.social || [];
         cursor: pointer;
         color: color-mix(in oklab, var(--foreground) 76%, var(--muted-foreground));
         background-color: transparent;
-        transition: color 0.15s, background-color 0.15s;
+        transition:
+            color 0.15s,
+            background-color 0.15s;
         text-decoration: none;
     }
     a:hover {

package/components/overrides/ThemeSelect.astro

@@ -2,7 +2,7 @@
 
 ---
 
-<starlight-theme-lucode-select>
+<starlight-theme-grove-select>
     <button
         aria-label={Astro.locals.t('themeSelect.accessibleLabel')}
         aria-live="polite"
@@ -49,7 +49,7 @@
 
         <span class="sr-only">Toggle theme</span>
     </button>
-</starlight-theme-lucode-select>
+</starlight-theme-grove-select>
 
 <style>
     button {
@@ -137,8 +137,8 @@
     });
 
     customElements.define(
-        'starlight-theme-lucode-select',
-        class StarlightThemeLucodeSelect extends HTMLElement {
+        'starlight-theme-grove-select',
+        class StarlightThemeGroveSelect extends HTMLElement {
             constructor() {
                 super();
                 onThemeChange(loadTheme());

package/components/overrides/TwoColumnContent.astro

@@ -42,7 +42,7 @@ const { toc } = Astro.locals.starlightRoute;
     }
 
     .main {
-        max-width: 40rem;
+        max-width: var(--content-max-width);
         min-width: 0;
         width: 100%;
         margin-inline: auto;

package/components/overrides/parts/Drawer.astro

@@ -1,10 +1,19 @@
 ---
-import userConfig from 'virtual:lucode-starlight-config';
-import { getTranslation } from './NavBar.astro';
 import { getRelativeLocaleUrl } from 'astro:i18n';
-const { sidebar } = Astro.locals.starlightRoute;
+import userConfig from 'virtual:grove-starlight-config';
+import starlightConfig from 'virtual:starlight/user-config';
+import { createLocaleLookup, resolveNavLabel } from '../../../core/i18n';
+
+const { sidebar, lang, locale } = Astro.locals.starlightRoute;
 
 const currentPath = Astro.url.pathname;
+
+const localeKeys = createLocaleLookup({
+  lang,
+  locale: Astro.currentLocale ?? locale,
+  defaultLang: starlightConfig.defaultLocale?.lang,
+  defaultLocale: starlightConfig.defaultLocale?.locale,
+});
 ---
 
 <div popover="auto" id="drawer">
@@ -25,10 +34,7 @@ const currentPath = Astro.url.pathname;
                             !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 href={link} {...nav.attrs}>