starlight-telescope 0.0.1

package/src/libs/url.ts

@@ -0,0 +1,125 @@
+/**
+ * URL utilities for building locale-aware URLs.
+ * Based on the starlight-tags plugin's approach.
+ * @see https://github.com/HiDeoo/starlight-blog/blob/main/packages/starlight-blog/libs/page.ts
+ */
+
+// Lazy-loaded config to avoid circular dependencies
+let starlightLocales: Record<string, unknown> | undefined;
+
+function getLocales(): Record<string, unknown> | undefined {
+  if (starlightLocales === undefined) {
+    try {
+      // @ts-expect-error - virtual module
+      const config = import.meta.env.STARLIGHT_LOCALES;
+      starlightLocales = config ? JSON.parse(config) : undefined;
+    } catch {
+      starlightLocales = undefined;
+    }
+  }
+  return starlightLocales;
+}
+
+/**
+ * Get the base URL with trailing slash removed.
+ */
+export function getBase(): string {
+  return import.meta.env.BASE_URL.replace(/\/$/, '');
+}
+
+/**
+ * Extract locale from a URL path's first segment.
+ * Returns undefined if no locale found (root locale).
+ */
+export function getLocaleFromPath(path: string): string | undefined {
+  // Remove leading slash and get first segment
+  const segments = path.replace(/^\//, '').split('/');
+  const firstSegment = segments[0];
+
+  if (!firstSegment) return undefined;
+
+  // Check against configured locales if available
+  const locales = getLocales();
+  if (locales && firstSegment in locales) {
+    return firstSegment;
+  }
+
+  // Fallback: check if it looks like a locale code (e.g., 'en', 'fr', 'en-us', 'pt-br')
+  // This handles cases where we can't access the config
+  //
+  // We use a stricter pattern to avoid false positives with common path segments.
+  // Valid patterns:
+  // - Exactly 2 lowercase letters (ISO 639-1): en, fr, de, es, ja, zh
+  // - 2 letters + hyphen + 2 letters/digits (regional): en-us, pt-br, zh-cn
+  // - 2 letters + hyphen + 4 letters (script variants): zh-hans, zh-hant
+  //
+  // Explicitly excluded common false positives: api, src, css, img, lib, etc.
+  const commonPathSegments = new Set([
+    'api', 'src', 'css', 'img', 'lib', 'app', 'bin', 'doc', 'log', 'tmp', 'var', 'opt', 'usr', 'etc'
+  ]);
+
+  if (commonPathSegments.has(firstSegment)) {
+    return undefined;
+  }
+
+  // Match strict locale patterns: xx or xx-xx or xx-xxxx
+  if (/^[a-z]{2}(-[a-z]{2,4})?$/.test(firstSegment)) {
+    return firstSegment;
+  }
+
+  return undefined;
+}
+
+/**
+ * Extract locale from an Astro URL, accounting for base path.
+ */
+export function getLocaleFromUrl(url: URL): string | undefined {
+  const base = getBase();
+  const pathAfterBase = url.pathname.slice(base.length);
+  return getLocaleFromPath(pathAfterBase);
+}
+
+/**
+ * Build a localized URL from a relative path.
+ *
+ * @param path - Relative path (e.g., 'getting-started')
+ * @param locale - Locale string or undefined for root locale
+ * @returns Full URL with base and locale (e.g., '/docs/fr/getting-started')
+ */
+export function buildUrl(path: string, locale: string | undefined): string {
+  const base = getBase();
+  const localeSegment = locale ? `/${locale}` : '';
+
+  // Ensure path starts with /
+  const normalizedPath = path.startsWith('/') ? path : `/${path}`;
+
+  return `${base}${localeSegment}${normalizedPath}`;
+}
+
+/**
+ * Build a localized URL, extracting locale from the current page URL.
+ * Use this when you don't have access to Astro.params.
+ *
+ * @param path - Relative path (e.g., 'getting-started')
+ * @param currentUrl - The current page's URL (Astro.url)
+ * @returns Full URL with base and locale
+ */
+export function buildUrlFromCurrentPage(path: string, currentUrl: URL): string {
+  const locale = getLocaleFromUrl(currentUrl);
+  return buildUrl(path, locale);
+}
+
+/**
+ * Strip locale prefix from a path if present.
+ *
+ * @param path - Path that may include locale prefix (e.g., 'fr/getting-started')
+ * @returns Path without locale prefix (e.g., 'getting-started')
+ */
+export function stripLocaleFromPath(path: string): string {
+  const locale = getLocaleFromPath(path);
+  if (locale) {
+    // Remove locale and the following slash
+    return path.slice(locale.length + 1);
+  }
+  return path;
+}

package/src/libs/vite.ts

@@ -0,0 +1,19 @@
+import type { Plugin as VitePlugin } from 'vite';
+import type { TelescopeConfig } from '../schemas/config.js';
+
+export function vitePluginTelescopeConfig(config: TelescopeConfig): VitePlugin {
+  const VIRTUAL_ID = 'virtual:starlight-telescope-config';
+  const RESOLVED_ID = '\0' + VIRTUAL_ID;
+
+  return {
+    name: 'vite-plugin-starlight-telescope',
+    resolveId(id) {
+      if (id === VIRTUAL_ID) return RESOLVED_ID;
+    },
+    load(id) {
+      if (id === RESOLVED_ID) {
+        return `export default ${JSON.stringify(config)};`;
+      }
+    },
+  };
+}

package/src/pages/pages.json.ts

@@ -0,0 +1,72 @@
+import type { APIRoute, GetStaticPaths } from 'astro';
+import { getCollection } from 'astro:content';
+// @ts-expect-error - virtual module provided by Starlight
+import starlightConfig from 'virtual:starlight/user-config';
+import type { TelescopePage } from '../schemas/config.js';
+import { getLocaleFromPath, stripLocaleFromPath } from '../libs/url.js';
+
+/**
+ * Generate static paths for all supported locales.
+ * Creates /pages.json for root locale and /[locale]/pages.json for each configured locale.
+ */
+export const getStaticPaths: GetStaticPaths = () => {
+  const configuredLocales = starlightConfig.locales
+    ? Object.keys(starlightConfig.locales).filter((l) => l !== 'root')
+    : [];
+
+  return [
+    // Root locale (no prefix)
+    { params: { locale: undefined } },
+    // Each configured locale
+    ...configuredLocales.map((locale) => ({
+      params: { locale },
+    })),
+  ];
+};
+
+export const GET: APIRoute = async ({ params }) => {
+  const { locale } = params;
+
+  try {
+    const allPages = await getCollection('docs');
+
+    // Filter pages by locale
+    const localePages = allPages.filter((page) => {
+      const pageLocale = getLocaleFromPath(page.id);
+
+      if (locale === undefined) {
+        // Root locale: pages without locale prefix
+        return pageLocale === undefined;
+      }
+      // Specific locale: pages with matching locale prefix
+      return pageLocale === locale;
+    });
+
+    // Filter out the home page (served at /, not /index)
+    const filteredPages = localePages.filter(
+      (page) => stripLocaleFromPath(page.id) !== 'index'
+    );
+
+    // Format pages, stripping locale from path since it's already implicit
+    const formattedPages: TelescopePage[] = filteredPages.map((page) => ({
+      title: page.data.title,
+      // Strip locale prefix from path - navigation will add it back
+      path: stripLocaleFromPath(page.id),
+      description: page.data.description || '',
+      tags: page.data.tags || [],
+    }));
+
+    return new Response(JSON.stringify(formattedPages), {
+      headers: {
+        'Content-Type': 'application/json',
+        'Cache-Control': 'max-age=3600', // Cache for 1 hour
+      },
+    });
+  } catch (error) {
+    console.error('Error generating pages.json:', error);
+    return new Response(JSON.stringify({ error: 'Failed to generate pages' }), {
+      status: 500,
+      headers: { 'Content-Type': 'application/json' },
+    });
+  }
+};

package/src/schemas/config.ts

@@ -0,0 +1,103 @@
+import { z } from 'zod';
+
+// Keyboard shortcut schema
+export const ShortcutSchema = z
+  .object({
+    key: z.string().default('/'),
+    ctrl: z.boolean().default(true),
+    meta: z.boolean().default(true), // Cmd on Mac
+    shift: z.boolean().default(false),
+    alt: z.boolean().default(false),
+  })
+  .default({
+    key: '/',
+    ctrl: true,
+    meta: true,
+    shift: false,
+    alt: false,
+  });
+
+// Fuse.js options schema - optimized for quick page navigation
+export const FuseOptionsSchema = z
+  .object({
+    threshold: z.number().min(0).max(1).default(0.3),
+    ignoreLocation: z.boolean().default(true),
+    distance: z.number().default(100),
+    minMatchCharLength: z.number().default(2),
+    findAllMatches: z.boolean().default(false),
+    keys: z
+      .array(
+        z.object({
+          name: z.string(),
+          weight: z.number(),
+        })
+      )
+      .default([
+        { name: 'title', weight: 1.0 },
+        { name: 'path', weight: 0.6 },
+        { name: 'tags', weight: 0.5 },
+        { name: 'description', weight: 0.3 },
+      ]),
+  })
+  .default({
+    threshold: 0.3,
+    ignoreLocation: true,
+    distance: 100,
+    minMatchCharLength: 2,
+    findAllMatches: false,
+    keys: [
+      { name: 'title', weight: 1.0 },
+      { name: 'path', weight: 0.6 },
+      { name: 'tags', weight: 0.5 },
+      { name: 'description', weight: 0.3 },
+    ],
+  });
+
+// Theme customization schema
+export const ThemeSchema = z
+  .object({
+    overlayBackground: z.string().optional(),
+    modalBackground: z.string().optional(),
+    modalBackgroundAlt: z.string().optional(),
+    accentColor: z.string().optional(),
+    accentHover: z.string().optional(),
+    accentSelected: z.string().optional(),
+    textPrimary: z.string().optional(),
+    textSecondary: z.string().optional(),
+    border: z.string().optional(),
+    borderActive: z.string().optional(),
+    pinColor: z.string().optional(),
+    tagColor: z.string().optional(),
+  })
+  .default({});
+
+// Main config schema
+export const TelescopeConfigSchema = z
+  .object({
+    shortcut: ShortcutSchema,
+    fuseOptions: FuseOptionsSchema,
+    recentPagesCount: z.number().min(0).max(20).default(5),
+    maxResults: z.number().min(1).max(100).default(20),
+    debounceMs: z.number().min(0).max(1000).default(100),
+    theme: ThemeSchema,
+  })
+  .default({
+    recentPagesCount: 5,
+    maxResults: 20,
+    debounceMs: 100,
+  });
+
+// Inferred types
+export type TelescopeConfig = z.infer<typeof TelescopeConfigSchema>;
+export type TelescopeUserConfig = z.input<typeof TelescopeConfigSchema>;
+export type TelescopeShortcut = z.infer<typeof ShortcutSchema>;
+export type TelescopeFuseOptions = z.infer<typeof FuseOptionsSchema>;
+export type TelescopeTheme = z.infer<typeof ThemeSchema>;
+
+// Page data structure
+export interface TelescopePage {
+  title: string;
+  path: string;
+  description?: string;
+  tags?: string[];
+}