starlight-versions 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,30 @@
+# starlight-versions
+
+## 0.4.0
+
+### Minor Changes
+
+- [#15](https://github.com/HiDeoo/starlight-versions/pull/15) [`ecd96ed`](https://github.com/HiDeoo/starlight-versions/commit/ecd96ed4aa4474bb418669e8113bb9e1af0f7536) Thanks [@HiDeoo](https://github.com/HiDeoo)! - Adds support for Astro v5, drops support for Astro v4.
+
+  ⚠️ **BREAKING CHANGE:** The minimum supported version of Starlight is now `0.30.0`.
+
+  Please follow the [upgrade guide](https://github.com/withastro/starlight/releases/tag/%40astrojs/starlight%400.30.0) to update your project.
+
+  After upgrading, you will also need to update the `versions` collection in your `src/content.config.ts` file to use the new `docsVersionsLoader`:
+
+  ```diff
+   // src/content.config.ts
+   import { defineCollection } from "astro:content";
+   import { docsLoader } from "@astrojs/starlight/loaders";
+   import { docsSchema } from "@astrojs/starlight/schema";
+  -import { docsVersionsSchema } from 'starlight-versions/schema'
+  +import { docsVersionsLoader } from 'starlight-versions/loader'
+
+   export const collections = {
+     docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }),
+  -  versions: defineCollection({ type: 'data', schema: docsVersionsSchema() }),
+  +  versions: defineCollection({ loader: docsVersionsLoader() }),
+   };
+  ```
+
+  Note that the [`legacy.collections` flag](https://docs.astro.build/en/reference/legacy-flags/#collections) is not supported by this plugin and you should update your collections to use Astro's new Content Layer API.

package/components/VersionSearch.astro

@@ -26,18 +26,22 @@ const pagefindTranslations = {
 
 const pageVersion = getVersionFromSlug(starlightVersionsConfig, starlightConfig, entry.slug)
 const pageVersionIdentifier = getVersionIdentifier(pageVersion)
+
+const dataAttributes: DOMStringMap = {
+  'data-pagefind-filter': `version:${pageVersionIdentifier}`,
+  'data-translations': JSON.stringify(pagefindTranslations),
+  'data-version': pageVersionIdentifier,
+}
+if (project.trailingSlash === 'never') dataAttributes['data-strip-trailing-slash'] = ''
 ---
 
-<site-search
-  data-translations={JSON.stringify(pagefindTranslations)}
-  data-strip-trailing-slash={project.trailingSlash === 'never'}
-  data-version={pageVersionIdentifier}
-  data-pagefind-filter={`version:${pageVersionIdentifier}`}
->
+<site-search class={Astro.props['class']} {...dataAttributes}>
   <button data-open-modal disabled>
-    <Icon name="magnifier" label={Astro.locals.t('search.label')} />
+    <Icon name="magnifier" />
     <span class="sl-hidden md:sl-block" aria-hidden="true">{Astro.locals.t('search.label')}</span>
-    <Icon name="forward-slash" class="sl-hidden md:sl-block" label={Astro.locals.t('search.shortcutLabel')} />
+    <kbd class="sl-hidden md:sl-flex" style="display: none;">
+      <kbd>{Astro.locals.t('search.ctrlKey')}</kbd><kbd>K</kbd>
+    </kbd>
   </button>
 
   <dialog style="padding:0" aria-label={Astro.locals.t('search.label')}>
@@ -72,6 +76,27 @@ const pageVersionIdentifier = getVersionIdentifier(pageVersion)
   </dialog>
 </site-search>
 
+{
+  /**
+   * This is intentionally inlined to avoid briefly showing an invalid shortcut.
+   * Purposely using the deprecated `navigator.platform` property to detect Apple devices, as the
+   * user agent is spoofed by some browsers when opening the devtools.
+   */
+}
+<script is:inline>
+  ;(() => {
+    const openBtn = document.querySelector('button[data-open-modal]')
+    const shortcut = openBtn?.querySelector('kbd')
+    if (!openBtn || !(shortcut instanceof HTMLElement)) return
+    const platformKey = shortcut.querySelector('kbd')
+    if (platformKey && /(Mac|iPhone|iPod|iPad)/i.test(navigator.platform)) {
+      platformKey.textContent = '⌘'
+      openBtn.setAttribute('aria-keyshortcuts', 'Meta+K')
+    }
+    shortcut.style.display = ''
+  })()
+</script>
+
 <script>
   class SiteSearch extends HTMLElement {
     constructor() {
@@ -95,7 +120,7 @@ const pageVersionIdentifier = getVersionIdentifier(pageVersion)
         document.body.toggleAttribute('data-search-modal-open', true)
         this.querySelector('input')?.focus()
         event?.stopPropagation()
-        window.addEventListener('click', onClick)
+        globalThis.addEventListener('click', onClick)
       }
 
       const closeModal = () => dialog.close()
@@ -106,20 +131,17 @@ const pageVersionIdentifier = getVersionIdentifier(pageVersion)
 
       dialog.addEventListener('close', () => {
         document.body.toggleAttribute('data-search-modal-open', false)
-        window.removeEventListener('click', onClick)
+        globalThis.removeEventListener('click', onClick)
       })
 
-      // Listen for `/`, `ctrl + k`, and `cmd + k` keyboard shortcuts.
-      window.addEventListener('keydown', (e) => {
-        const isInput =
-          document.activeElement instanceof HTMLElement &&
-          (['input', 'select', 'textarea'].includes(document.activeElement.tagName.toLowerCase()) ||
-            document.activeElement.isContentEditable)
+      // Listen for `ctrl + k` and `cmd + k` keyboard shortcuts.
+      globalThis.addEventListener('keydown', (e) => {
         if ((e.metaKey === true || e.ctrlKey === true) && e.key === 'k') {
-          dialog.open ? closeModal() : openModal()
-          e.preventDefault()
-        } else if (e.key === '/' && !dialog.open && !isInput) {
-          openModal()
+          if (dialog.open) {
+            closeModal()
+          } else {
+            openModal()
+          }
           e.preventDefault()
         }
       })
@@ -135,9 +157,9 @@ const pageVersionIdentifier = getVersionIdentifier(pageVersion)
       const formatURL = shouldStrip ? this.stripTrailingSlash : (path: string) => path
       const version = this.dataset['version'] ?? 'current'
 
-      window.addEventListener('DOMContentLoaded', () => {
+      globalThis.addEventListener('DOMContentLoaded', () => {
         if (import.meta.env.DEV) return
-        const onIdle = window.requestIdleCallback || ((cb) => setTimeout(cb, 1))
+        const onIdle = globalThis.requestIdleCallback || ((cb) => setTimeout(cb, 1))
         onIdle(async () => {
           // @ts-expect-error — Missing types for @pagefind/default-ui package.
           const { PagefindUI } = await import('@pagefind/default-ui')
@@ -189,7 +211,7 @@ const pageVersionIdentifier = getVersionIdentifier(pageVersion)
       border: 1px solid var(--sl-color-gray-5);
       border-radius: 0.5rem;
       padding-inline-start: 0.75rem;
-      padding-inline-end: 1rem;
+      padding-inline-end: 0.5rem;
       background-color: var(--sl-color-black);
       color: var(--sl-color-gray-2);
       font-size: var(--sl-text-sm);
@@ -206,6 +228,18 @@ const pageVersionIdentifier = getVersionIdentifier(pageVersion)
     }
   }
 
+  button > kbd {
+    border-radius: 0.25rem;
+    font-size: var(--sl-text-2xs);
+    gap: 0.25em;
+    padding-inline: 0.375rem;
+    background-color: var(--sl-color-gray-6);
+  }
+
+  kbd {
+    font-family: var(--__sl-font);
+  }
+
   dialog {
     margin: 0;
     background-color: var(--sl-color-gray-6);
@@ -217,7 +251,7 @@ const pageVersionIdentifier = getVersionIdentifier(pageVersion)
     box-shadow: var(--sl-shadow-lg);
   }
   dialog[open] {
-    display: grid;
+    display: flex;
   }
 
   dialog::backdrop {
@@ -227,7 +261,10 @@ const pageVersionIdentifier = getVersionIdentifier(pageVersion)
   }
 
   .dialog-frame {
+    position: relative;
+    overflow: auto;
     flex-direction: column;
+    flex-grow: 1;
     gap: 1rem;
     padding: 1rem;
   }
@@ -383,6 +420,10 @@ const pageVersionIdentifier = getVersionIdentifier(pageVersion)
     border-radius: 0 0 var(--sl-search-corners) var(--sl-search-corners);
   }
 
+  #starlight__search .pagefind-ui__result-inner > .pagefind-ui__result-excerpt {
+    display: none;
+  }
+
   #starlight__search .pagefind-ui__result-inner > .pagefind-ui__result-title {
     padding: var(--sl-search-result-pad-block) var(--sl-search-result-pad-inline-end);
     padding-inline-start: var(--sl-search-result-pad-inline-start);

package/components/VersionSelect.astro

@@ -6,16 +6,16 @@ import starlightVersionsConfig from 'virtual:starlight-versions-config'
 
 import { getVersionFromSlug, getVersionURL } from '../libs/versions'
 
-const { slug } = Astro.props
+const { id } = Astro.props
 
-const pageVersion = getVersionFromSlug(starlightVersionsConfig, starlightConfig, slug)
+const pageVersion = getVersionFromSlug(starlightVersionsConfig, starlightConfig, id)
 ---
 
 <starlight-version-select>
   <label>
     <span class="sr-only">Select version</span>
     <Icon name="seti:clock" class="icon label-icon" />
-    <select value={pageVersion?.label ?? 'current'}>
+    <select value={pageVersion?.label ?? 'current'} autocomplete="off">
       <option
         selected={pageVersion === undefined}
         value={getVersionURL(starlightVersionsConfig, starlightConfig, Astro.url, undefined).pathname}
@@ -101,9 +101,23 @@ const pageVersion = getVersionFromSlug(starlightVersionsConfig, starlightConfig,
       constructor() {
         super()
 
-        this.querySelector('select')?.addEventListener('change', (event) => {
+        const select = this.querySelector('select')
+        if (!select) return
+
+        select?.addEventListener('change', (event) => {
           if (event.currentTarget instanceof HTMLSelectElement) {
-            window.location.pathname = event.currentTarget.value
+            globalThis.location.pathname = event.currentTarget.value
+          }
+        })
+
+        window.addEventListener('pageshow', (event) => {
+          if (!event.persisted) return
+          const markupSelectedIndex = select.querySelector<HTMLOptionElement>('option[selected]')?.index
+
+          // If the page was loaded from a cache, the version select selected index might not be in sync with the
+          // current page.
+          if (markupSelectedIndex !== select.selectedIndex) {
+            select.selectedIndex = markupSelectedIndex ?? 0
           }
         })
       }

package/loader.ts

@@ -0,0 +1,18 @@
+import { glob, type Loader } from 'astro/loaders'
+
+import { docsVersionsSchema } from './schema'
+
+const extensions = ['json', 'yml', 'yaml']
+
+export function docsVersionsLoader(): Loader {
+  return {
+    name: 'starlight-versions-loader',
+    load: (context) => {
+      return glob({
+        base: `${context.config.srcDir.pathname.replace(context.config.root.pathname, '')}content/versions`,
+        pattern: `**/[^_]*.{${extensions.join(',')}}`,
+      }).load(context)
+    },
+    schema: docsVersionsSchema(),
+  }
+}

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "starlight-versions",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "license": "MIT",
   "description": "Starlight plugin to version documentation pages.",
   "author": "HiDeoo <github@hideoo.dev> (https://hideoo.dev)",
   "type": "module",
   "exports": {
     ".": "./index.ts",
-    "./schema": "./schema.ts",
+    "./loader": "./loader.ts",
     "./components/VersionBanner.astro": "./components/VersionBanner.astro",
     "./components/VersionNotice.astro": "./components/VersionNotice.astro",
     "./components/VersionPagination.astro": "./components/VersionPagination.astro",
@@ -23,30 +23,31 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@pagefind/default-ui": "^1.0.3",
+    "@pagefind/default-ui": "^1.2.0",
     "github-slugger": "^2.0.0",
-    "mdast-util-mdx-jsx": "^3.1.2",
+    "mdast-util-mdx-jsx": "^3.1.3",
     "mdast-util-mdxjs-esm": "^2.0.1",
     "remark": "^15.0.1",
     "remark-frontmatter": "^5.0.0",
-    "remark-mdx": "^3.0.1",
+    "remark-mdx": "^3.1.0",
     "unist-util-visit": "^5.0.0",
-    "vfile": "^6.0.1",
-    "yaml": "^2.4.2"
+    "vfile": "^6.0.3",
+    "yaml": "^2.6.1"
   },
   "devDependencies": {
     "@types/mdast": "^4.0.4",
     "fast-glob": "^3.3.2",
-    "vitest": "^1.6.0"
+    "vitest": "2.1.6"
   },
   "peerDependencies": {
-    "@astrojs/starlight": ">=0.28.0"
+    "@astrojs/starlight": ">=0.30.0"
   },
   "engines": {
     "node": ">=18"
   },
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "provenance": true
   },
   "sideEffects": false,
   "keywords": [
@@ -66,6 +67,6 @@
   "bugs": "https://github.com/HiDeoo/starlight-versions/issues",
   "scripts": {
     "test": "vitest",
-    "lint": "prettier -c --cache . && eslint . --cache --max-warnings=0"
+    "lint": "eslint . --cache --max-warnings=0"
   }
 }