starlight-telescope 0.0.1

package/README.md

@@ -0,0 +1,15 @@
+# `starlight-telescope`
+
+Quickly navigate to any page in your Starlight docs with fuzzy search and keyboard-first navigation.
+
+## Documentation
+
+Want to get started immediately?
+
+Check out the `starlight-telescope` getting started guide.
+
+## License
+
+Licensed under the MIT License, Copyright © frostybee.
+
+See [LICENSE](https://github.com/frostybee/starlight-telescope/blob/main/LICENSE) for more information.

package/index.ts

@@ -0,0 +1,28 @@
+import type { StarlightPlugin } from '@astrojs/starlight/types';
+import { TelescopeConfigSchema, type TelescopeUserConfig } from './src/schemas/config.js';
+import starlightTelescopeIntegration from './src/libs/integration.js';
+
+export type {
+  TelescopeConfig,
+  TelescopeUserConfig,
+  TelescopePage,
+  TelescopeShortcut,
+  TelescopeFuseOptions,
+  TelescopeTheme,
+} from './src/schemas/config.js';
+
+export default function starlightTelescope(
+  userConfig: TelescopeUserConfig = {}
+): StarlightPlugin {
+  const config = TelescopeConfigSchema.parse(userConfig);
+
+  return {
+    name: 'starlight-telescope',
+    hooks: {
+      'config:setup'({ addIntegration, logger }) {
+        logger.info('Initializing Starlight Telescope search...');
+        addIntegration(starlightTelescopeIntegration(config));
+      },
+    },
+  };
+}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "starlight-telescope",
+  "version": "0.0.1",
+  "license": "MIT",
+  "description": "Quickly navigate to any page in your Starlight docs with fuzzy search and keyboard-first navigation.",
+  "author": "frostybee",
+  "type": "module",
+  "exports": {
+    ".": "./index.ts",
+    "./libs/telescope-search": "./src/libs/telescope-search.ts",
+    "./libs/telescope-element": "./src/libs/telescope-element.ts",
+    "./libs/modal": "./src/libs/modal.ts",
+    "./styles/telescope.css": "./src/styles/telescope.css",
+    "./schemas/config": "./src/schemas/config.ts"
+  },
+  "files": [
+    "index.ts",
+    "src/"
+  ],
+  "dependencies": {
+    "fuse.js": "^7.1.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@astrojs/starlight": "^0.37.4",
+    "astro": "^5.16.15"
+  },
+  "peerDependencies": {
+    "@astrojs/starlight": ">=0.37"
+  },
+  "engines": {
+    "node": "^18.17.1 || ^20.3.0 || >=21.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://github.com/frostybee/starlight-telescope",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/frostybee/starlight-telescope.git",
+    "directory": "packages/starlight-telescope"
+  },
+  "bugs": "https://github.com/frostybee/starlight-telescope/issues",
+  "keywords": [
+    "starlight",
+    "starlight-plugin",
+    "astro",
+    "search",
+    "fuzzy-search",
+    "navigation",
+    "withastro",
+    "command-palette"
+  ]  
+}

package/src/env.d.ts

@@ -0,0 +1,4 @@
+declare module 'virtual:starlight-telescope-config' {
+  const config: import('./schemas/config.js').TelescopeConfig;
+  export default config;
+}

package/src/libs/integration.ts

@@ -0,0 +1,82 @@
+import type { AstroIntegration } from 'astro';
+import type { TelescopeConfig } from '../schemas/config.js';
+import { fileURLToPath } from 'node:url';
+import { vitePluginTelescopeConfig } from './vite.js';
+
+export default function starlightTelescopeIntegration(
+  config: TelescopeConfig
+): AstroIntegration {
+  return {
+    name: 'starlight-telescope-integration',
+    hooks: {
+      'astro:config:setup': ({ injectRoute, injectScript, updateConfig }) => {
+        // 1. Register Vite plugin for virtual module
+        updateConfig({
+          vite: { plugins: [vitePluginTelescopeConfig(config)] },
+        });
+
+        // 2. Inject locale-aware /pages.json route
+        // Using [...locale] rest parameter handles both localized (/en/pages.json)
+        // and non-localized (/pages.json) paths in a single route
+        injectRoute({
+          pattern: '/[...locale]/pages.json',
+          entrypoint: fileURLToPath(new URL('../pages/pages.json.ts', import.meta.url)),
+        });
+
+        // 3. Inject CSS
+        injectScript('page', `import 'starlight-telescope/styles/telescope.css';`);
+
+        // 4. Inject client-side script with custom element
+        // Use base64 encoding for safe config transport (avoids XSS via string escaping)
+        const configBase64 = Buffer.from(JSON.stringify(config)).toString('base64');
+
+        injectScript(
+          'page',
+          `
+          import 'starlight-telescope/libs/telescope-element';
+
+          let initInProgress = false;
+
+          function initTelescope() {
+            // Prevent race conditions with initialization lock
+            if (window.__telescopeInitialized || initInProgress) return;
+            initInProgress = true;
+
+            try {
+              // Inject custom element into header
+              if (!document.querySelector('telescope-search')) {
+                const rightGroup = document.querySelector('.right-group');
+                if (rightGroup) {
+                  const el = document.createElement('telescope-search');
+                  // Decode base64 config safely
+                  const configJson = atob('${configBase64}');
+                  el.setAttribute('data-config', configJson);
+                  rightGroup.insertAdjacentElement('afterbegin', el);
+                }
+              }
+              window.__telescopeInitialized = true;
+            } finally {
+              initInProgress = false;
+            }
+          }
+
+          if (document.readyState === 'loading') {
+            document.addEventListener('DOMContentLoaded', initTelescope);
+          } else {
+            initTelescope();
+          }
+
+          document.addEventListener('astro:page-load', () => {
+            window.__telescopeInitialized = false;
+            initTelescope();
+          });
+        `
+        );
+      },
+
+      'astro:build:done': ({ logger }) => {
+        logger.info('Starlight Telescope plugin installed successfully!');
+      },
+    },
+  };
+}

package/src/libs/modal.ts

@@ -0,0 +1,43 @@
+export function getModalHTML(): string {
+  return `
+    <dialog id="telescope-dialog" class="telescope" aria-label="Site search">
+      <div class="telescope__modal">
+        <button class="telescope__close-button" id="telescope-close-button" aria-label="Close">
+          <svg aria-hidden="true" viewBox="0 0 24 24"><path d="M18 6L6 18M6 6l12 12" stroke-linecap="round"/></svg>
+        </button>
+        <div class="telescope__tabs" role="tablist">
+          <button class="telescope__tab telescope__tab--active" data-tab="search" role="tab" aria-selected="true" id="tab-search">Search</button>
+          <button class="telescope__tab" data-tab="recent" role="tab" aria-selected="false" id="tab-recent">Recent</button>
+        </div>
+        <div class="telescope__search-header">
+          <input id="telescope-search-input" class="telescope__search-input" type="text"
+            role="combobox"
+            aria-expanded="true"
+            aria-autocomplete="list"
+            aria-haspopup="listbox"
+            aria-controls="telescope-results"
+            aria-activedescendant=""
+            placeholder="Search pages..." autocomplete="off" spellcheck="false">
+        </div>
+        <div id="telescope-search-section" class="telescope__section telescope__section--active" role="tabpanel" aria-labelledby="tab-search">
+          <div id="telescope-loading" class="telescope__loading">
+            <div class="telescope__spinner"></div>
+            <span>Loading pages...</span>
+          </div>
+          <ul id="telescope-results" class="telescope__results" role="listbox" aria-label="Search results"></ul>
+        </div>
+        <div id="telescope-recent-section" class="telescope__section" role="tabpanel" aria-labelledby="tab-recent">
+          <ul id="telescope-recent-results" class="telescope__results" role="listbox" aria-label="Recent pages"></ul>
+        </div>
+        <div id="telescope-live-region" class="sr-only" aria-live="polite" aria-atomic="true"></div>
+        <div class="telescope__footer">
+          <div class="telescope__shortcuts">
+            <span><kbd>↑</kbd><kbd>↓</kbd> navigate</span>
+            <span><kbd>↵</kbd> select</span>
+            <span><kbd>Space</kbd> pin</span>
+            <span><kbd>Esc</kbd> close</span>
+          </div>
+        </div>
+      </div>
+    </dialog>`;
+}

package/src/libs/telescope-element.ts

@@ -0,0 +1,73 @@
+import TelescopeSearch from './telescope-search.js';
+import { getModalHTML } from './modal.js';
+import type { TelescopeConfig } from '../schemas/config.js';
+
+export class TelescopeSearchElement extends HTMLElement {
+  private telescopeSearch: TelescopeSearch | null = null;
+
+  connectedCallback() {
+    const configStr = this.dataset.config;
+    if (!configStr) {
+      console.error('[Telescope] Missing data-config attribute');
+      return;
+    }
+
+    let config: TelescopeConfig;
+    try {
+      config = JSON.parse(configStr);
+    } catch (e) {
+      console.error('[Telescope] Invalid config JSON:', e);
+      return;
+    }
+
+    // Render trigger button
+    this.innerHTML = this.getTriggerButtonHTML();
+
+    // Platform detection for Mac (userAgentData with fallback to userAgent)
+    const shortcutKey = this.querySelector('.telescope__shortcut-key');
+    const isMac = (navigator as Navigator & { userAgentData?: { platform: string } }).userAgentData?.platform === 'macOS'
+      || /Mac|iPhone|iPod|iPad/i.test(navigator.userAgent);
+    if (shortcutKey && isMac) {
+      shortcutKey.textContent = '⌘';
+      this.querySelector('button')?.setAttribute('aria-keyshortcuts', 'Meta+/');
+    }
+
+    // Inject dialog if not present
+    if (!document.getElementById('telescope-dialog')) {
+      document.body.insertAdjacentHTML('beforeend', getModalHTML());
+    }
+
+    // Initialize search controller
+    this.telescopeSearch = new TelescopeSearch(config);
+
+    // Button click opens modal
+    this.querySelector('button')?.addEventListener('click', () => {
+      this.telescopeSearch?.open();
+    });
+  }
+
+  disconnectedCallback() {
+    // Cleanup to prevent memory leaks
+    this.telescopeSearch?.destroy();
+    this.telescopeSearch = null;
+  }
+
+  private getTriggerButtonHTML(): string {
+    return `<button class="telescope__trigger-btn" aria-label="Open Telescope Search" aria-keyshortcuts="Control+/">
+      <svg aria-hidden="true" viewBox="0 0 24 24" width="20" height="20" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+        <path d="m10.065 12.493-6.18 1.318a.934.934 0 0 1-1.108-.702l-.537-2.15a1.07 1.07 0 0 1 .691-1.265l13.504-4.44"/>
+        <path d="m13.56 11.747 4.332-.924"/>
+        <path d="m16 21-3.105-6.21"/>
+        <path d="M16.485 5.94a2 2 0 0 1 1.455-2.425l1.09-.272a1 1 0 0 1 1.212.727l1.515 6.06a1 1 0 0 1-.727 1.213l-1.09.272a2 2 0 0 1-2.425-1.455z"/>
+        <path d="m6.158 8.633 1.114 4.456"/>
+        <path d="m8 21 3.105-6.21"/>
+      </svg>
+      <kbd class="telescope__shortcut sl-hidden md:sl-flex">
+        <kbd class="telescope__shortcut-key">Ctrl</kbd>
+        <kbd>/</kbd>
+      </kbd>
+    </button>`;
+  }
+}
+
+customElements.define('telescope-search', TelescopeSearchElement);