@grove-dev/starlight 0.6.1 → 0.8.0

package/core/config/override.ts

@@ -1,48 +1,52 @@
 import type { HookParameters } from '@astrojs/starlight/types';
 import type { AstroIntegrationLogger } from 'astro';
+import type { GroveStarlightConfig } from './schemas';
 
 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',
+  '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
+  starlightConfig: StarlightUserConfig,
+  pluginConfig: GroveStarlightConfig,
+  overrides: ComponentOverride[],
+  logger: AstroIntegrationLogger,
 ): StarlightUserConfig['components'] {
-    const components = { ...starlightConfig.components };
-    for (const override of overrides) {
-        if (starlightConfig.components?.[override] != null) {
-            const fallback = `@grove-dev/starlight/components/overrides/${override}.astro`;
+  const components = { ...starlightConfig.components };
+  for (const override of overrides) {
+    if (starlightConfig.components?.[override] != null) {
+      const fallback = `@grove-dev/starlight/components/overrides/${override}.astro`;
 
-            logger.warn(
-                `A \`<${override}>\` component override is already defined in your Starlight configuration.`
-            );
-            logger.warn(
-                `To use \`@grove-dev/starlight/components\`, either remove this override or manually render the content from \`${fallback}\`.`
-            );
-            continue;
-        }
-        components[override] = `@grove-dev/starlight/components/overrides/${override}.astro`;
+      if (pluginConfig.warnOverrides) {
+        logger.warn(
+          `A \`<${override}>\` component override is already defined in your Starlight configuration.`,
+        );
+        logger.warn(
+          `To use \`@grove-dev/starlight/components\`, either remove this override or manually render the content from \`${fallback}\`.`,
+        );
+      }
+      continue;
     }
+    components[override] = `@grove-dev/starlight/components/overrides/${override}.astro`;
+  }
 
-    return components;
+  return components;
 }

package/core/config/schemas.ts

@@ -3,55 +3,76 @@ 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()])
+  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(),
+  /**
+   * 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 link label.
+   *
+   * - A string used as the default-locale label (pair with `translations` for other languages).
+   * - Or a locale map keyed by BCP-47 tags / locale paths (e.g. `en`, `es`).
+   *
+   * @see https://starlight.astro.build/guides/sidebar/#internationalization
+   */
+  label: z.union([z.string(), z.record(z.string(), z.string())]),
+  /**
+   * Optional labels for other languages when `label` is a string.
+   * Keys should be BCP-47 tags (e.g. `en`, `es`), matching Starlight sidebar translations.
+   *
+   * @see https://starlight.astro.build/guides/sidebar/#internationalization
+   */
+  translations: z.record(z.string(), z.string()).optional(),
+  /**
+   * 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 const GroveStarlightConfigSchema = z.object({
+  /** Array of navigation links for the header/nav bar. */
+  navLinks: z.array(linkSchema).optional(),
+  docs: z
+    .object({
+      includeAiUtilities: z.boolean().optional().default(false),
+    })
+    .optional()
+    .default({ includeAiUtilities: false }),
+  /**
+   * Whether to warn when a component override defined in your Starlight configuration prevents
+   * the theme from applying its own. Set to `false` to silence those warnings.
+   */
+  warnOverrides: z.boolean().optional().default(true),
+  /**
+   * Footer Markdown text. Can be a string, or for multilingual sites an object with values for
+   * each locale. Keys may be BCP-47 tags (e.g. `en`, `es`) or locale paths.
+   *
+   * @see https://starlight.astro.build/reference/configuration/#title
+   */
+  footerText: z
+    .union([z.string(), z.record(z.string(), 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). Originally forked from [lucas-labs/lucode-starlight-theme](https://github.com/lucas-labs/lucode-starlight-theme) and maintained by [grove](https://github.com/tortuvshin/grove).',
+    ),
 });
 
-export type LucodeStarlightUserConfig = z.input<typeof LucodeStarlightConfigSchema>;
-export type LucodeStarlightConfig = z.output<typeof LucodeStarlightConfigSchema>;
+export type GroveStarlightUserConfig = z.input<typeof GroveStarlightConfigSchema>;
+export type GroveStarlightConfig = z.output<typeof GroveStarlightConfigSchema>;

package/core/config/vite.ts

@@ -1,20 +1,20 @@
 import type { ViteUserConfig } from 'astro';
-import type { LucodeStarlightConfig } from './schemas';
+import type { GroveStarlightConfig } 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)}`;
+export function vitePlugin(config: GroveStarlightConfig): VitePlugin {
+  const moduleId = 'virtual:grove-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;
-        },
-    };
+  return {
+    name: 'vite-plugin-grove-starlight',
+    load(id) {
+      return id === resolvedModuleId ? moduleContent : undefined;
+    },
+    resolveId(id) {
+      return id === moduleId ? resolvedModuleId : undefined;
+    },
+  };
 }
 
 type VitePlugin = NonNullable<ViteUserConfig['plugins']>[number];

package/core/i18n.ts

@@ -0,0 +1,175 @@
+export type LocaleLookup = {
+  /** BCP-47 tag from the active locale (`locales[x].lang`), e.g. `en`. */
+  lang?: string;
+  /** Locale path key (`Astro.currentLocale`), e.g. `en`. */
+  locale?: string;
+  /** Default locale BCP-47 tag or path used as fallback. */
+  defaultLang: string;
+  /** Default locale path key, e.g. `en`. */
+  defaultLocale?: string;
+};
+
+/**
+ * Pick a value from a locale dictionary.
+ *
+ * Tries exact then case-insensitive matches for active locale candidates first,
+ * then the same for fallback/default candidates. This covers Starlight setups
+ * where config keys are BCP-47 (`es-ES`) but `Astro.currentLocale` is the path
+ * (`es-es`), without letting the default locale shadow an active case-insensitive hit.
+ */
+export function pickLocalized(
+  dictionary: Record<string, string> | undefined,
+  candidates: Array<string | undefined>,
+  fallbacks: Array<string | undefined> = [],
+): string | undefined {
+  if (!dictionary) {
+    return undefined;
+  }
+
+  const lowerMap = Object.fromEntries(
+    Object.entries(dictionary).map(([key, value]) => [key.toLowerCase(), value]),
+  );
+
+  const pickExact = (keys: Array<string | undefined>) => {
+    for (const key of keys) {
+      if (key && dictionary[key]) {
+        return dictionary[key];
+      }
+    }
+    return undefined;
+  };
+
+  const pickCaseInsensitive = (keys: Array<string | undefined>) => {
+    for (const key of keys) {
+      if (!key) {
+        continue;
+      }
+
+      const match = lowerMap[key.toLowerCase()];
+      if (match) {
+        return match;
+      }
+    }
+    return undefined;
+  };
+
+  return (
+    pickExact(candidates) ??
+    pickCaseInsensitive(candidates) ??
+    pickExact(fallbacks) ??
+    pickCaseInsensitive(fallbacks)
+  );
+}
+
+/** @deprecated Prefer `pickLocalized`. Kept for existing call sites/tests. */
+export function pickLang(
+  dictionary: Record<string, string> | undefined,
+  lang: string,
+): string | undefined {
+  return pickLocalized(dictionary, [lang]);
+}
+
+function activeKeys({ lang, locale }: LocaleLookup): Array<string | undefined> {
+  return [lang, locale];
+}
+
+function fallbackKeys({ defaultLang, defaultLocale }: LocaleLookup): Array<string | undefined> {
+  return [defaultLang, defaultLocale];
+}
+
+/**
+ * Resolve a nav link label.
+ *
+ * Supports both APIs:
+ * - Starlight sidebar style: `label: string` + optional `translations`
+ * - Locale map style: `label: Record<BCP-47 | locale-path, string>`
+ */
+export function resolveNavLabel(
+  label: string | Record<string, string>,
+  translations: Record<string, string> | undefined,
+  keys: LocaleLookup,
+): string {
+  const primary = activeKeys(keys);
+  const fallback = fallbackKeys(keys);
+
+  if (typeof label === 'string') {
+    return pickLocalized(translations, primary, fallback) || label;
+  }
+
+  const resolved = pickLocalized(label, primary, fallback);
+  if (resolved) {
+    return resolved;
+  }
+
+  throw new Error(
+    `Localized label must include a key for the default language "${keys.defaultLang}".`,
+  );
+}
+
+/**
+ * Resolve a sidebar-style label: `translations[lang] ?? label`.
+ * Accepts a LocaleLookup or a bare lang string for convenience.
+ */
+export function resolveLabel(
+  label: string,
+  translations: Record<string, string> | undefined,
+  langOrKeys: string | LocaleLookup,
+): string {
+  if (typeof langOrKeys === 'string') {
+    return pickLocalized(translations, [langOrKeys]) || label;
+  }
+
+  return resolveNavLabel(label, translations, langOrKeys);
+}
+
+/**
+ * Resolve a title-style localized string (`string | Record<string, string>`).
+ * Prefers the active language/locale, then falls back to the default language.
+ */
+export function resolveLocalizedString(
+  value: string | Record<string, string>,
+  langOrKeys: string | LocaleLookup,
+  defaultLang?: string,
+): string {
+  if (typeof value === 'string') {
+    return value;
+  }
+
+  const keys: LocaleLookup =
+    typeof langOrKeys === 'string'
+      ? { lang: langOrKeys, defaultLang: defaultLang ?? langOrKeys }
+      : langOrKeys;
+
+  const resolved = pickLocalized(value, activeKeys(keys), fallbackKeys(keys));
+  if (resolved) {
+    return resolved;
+  }
+
+  throw new Error(
+    `Localized string must include a key for the default language "${keys.defaultLang}".`,
+  );
+}
+
+/** Build a LocaleLookup from Starlight + Astro locale values. */
+export function createLocaleLookup(options: {
+  lang?: string;
+  locale?: string;
+  defaultLang?: string;
+  defaultLocale?: string;
+}): LocaleLookup {
+  const result: LocaleLookup = {
+    defaultLang: options.defaultLang || options.defaultLocale || 'en',
+  };
+
+  if (options.lang !== undefined) {
+    result.lang = options.lang;
+  }
+  if (options.locale !== undefined) {
+    result.locale = options.locale;
+  }
+  if (options.defaultLocale !== undefined) {
+    result.defaultLocale = options.defaultLocale;
+  }
+
+  return result;
+}

package/core/plugin.ts

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

package/core/sidebar.ts

@@ -0,0 +1,22 @@
+import type { StarlightRouteData } from '@astrojs/starlight/route-data';
+
+export type SidebarEntry = StarlightRouteData['sidebar'][number];
+export type SidebarGroup = Extract<SidebarEntry, { type: 'group' }>;
+export type SidebarLink = Extract<SidebarEntry, { type: 'link' }>;
+
+/** Every link reachable from `entries`, at any depth. */
+export function flattenSidebar(entries: SidebarEntry[]): SidebarLink[] {
+  return entries.flatMap((entry) =>
+    entry.type === 'group' ? flattenSidebar(entry.entries) : [entry],
+  );
+}
+
+/**
+ * Whether a group renders expanded.
+ *
+ * `collapsed` is the author's default, but a group holding the current page always opens, otherwise
+ * the reader would land on a page with no idea where they are in the tree.
+ */
+export function isSidebarGroupOpen(group: SidebarGroup): boolean {
+  return !group.collapsed || flattenSidebar(group.entries).some((link) => link.isCurrent);
+}

package/global.d.ts

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@grove-dev/starlight",
-  "version": "0.6.1",
+  "version": "0.8.0",
   "type": "module",
   "description": "Grove's theme for Starlight (the Astro native documentation site generator)",
   "author": "grove-dev",
@@ -9,7 +9,7 @@
     "node": ">=22.12.0"
   },
   "readme": "README.md",
-  "homepage": "https://grove.dev.mn/",
+  "homepage": "https://withgrove.dev/",
   "repository": {
     "type": "git",
     "url": "https://github.com/tortuvshin/grove.git",
@@ -21,18 +21,6 @@
   "publishConfig": {
     "access": "public"
   },
-  "files": [
-    "components",
-    "core",
-    "styles",
-    "global.d.ts",
-    "index.ts",
-    "schema.ts",
-    "user-components.ts",
-    "virtual.d.ts",
-    "README.md",
-    "THIRD_PARTY_LICENSES.md"
-  ],
   "exports": {
     ".": "./index.ts",
     "./schema": "./schema.ts",
@@ -59,14 +47,10 @@
     "./package.json": "./package.json"
   },
   "peerDependencies": {
-    "@astrojs/starlight": ">=0.38.3",
-    "astro": ">=5.0.0"
+    "@astrojs/starlight": ">=0.41.4"
   },
   "dependencies": {
     "@pagefind/default-ui": "^1.5.2",
     "marked": "^18.0.2"
-  },
-  "scripts": {
-    "test": "cd ../.. && pnpm exec vitest run --project starlight"
   }
 }