@abstractdata/starlight-theme 0.3.1 → 0.3.3

package/src/components/SocialIcons.astro

@@ -1,17 +1,32 @@
 ---
 /**
  * Override of Starlight's <SocialIcons /> slot.
- * Renders the default content, then appends the Abstract Data version chip
- * if `version` is configured on the theme plugin.
+ *
+ * Renders, in order:
+ *   1. <VersionPicker /> — auto-discovers versions from frontmatter; renders
+ *      nothing when fewer than 2 versions exist or the user isn't on an
+ *      API page. Zero-config: as soon as the autodoc orchestrator emits
+ *      versioned pages, the picker appears.
+ *   2. The default SocialIcons (GitHub, etc.).
+ *   3. The Abstract Data version chip if `version` is configured on the
+ *      theme plugin.
  *
  * The chip carries the `ad-version-chip` class. When `motion: 'full'`,
  * `hud.css` adds an idle glitch-pulse + a hover-triggered glitch.
+ *
+ * Why this lives in the plugin (not a user override): Starlight gives
+ * plugin-level `components` overrides higher precedence than user-level
+ * ones, so a user override would lose to ours and the version chip would
+ * disappear. Composing here keeps both features without conflicts.
  */
 import type { Props } from '@astrojs/starlight/props';
 import Default from '@astrojs/starlight/components/SocialIcons.astro';
+import VersionPicker from './VersionPicker.astro';
 import { config } from 'virtual:abstractdata/config';
 ---
 
+<VersionPicker apiBase={config.apiBase ?? '/api'} />
+
 <Default {...Astro.props} />
 
 {

package/src/components/VersionPicker.astro

@@ -0,0 +1,238 @@
+---
+/**
+ * <VersionPicker /> — dropdown for navigating between API doc versions.
+ *
+ * Two ways to use it:
+ *
+ * (a) Auto-discover (recommended). Pass no `versions` prop:
+ *
+ *   ---
+ *   import VersionPicker from '@abstractdata/starlight-theme/components/VersionPicker.astro';
+ *   ---
+ *   <VersionPicker apiBase="/api" />
+ *
+ * The component walks `getCollection('docs')` at build time, picks up
+ * every page that has a `version:` frontmatter field (set by the autodoc
+ * orchestrators on per-version pages), and dedupes by tag. The default
+ * version is detected via `versionDefault: true` on those same pages.
+ * No duplication: the autodoc JSON config is the canonical source.
+ *
+ * (b) Manual list. Pass an explicit `versions` array if you want to
+ * curate the dropdown — e.g. hide pre-release tags, reorder, override
+ * labels:
+ *
+ *   ---
+ *   const versions = [
+ *     { tag: 'v0.4.0', label: '0.4 (latest)', default: true },
+ *     { tag: 'v0.3.0', label: '0.3' },
+ *   ];
+ *   ---
+ *   <VersionPicker {versions} apiBase="/api" />
+ *
+ * On change the component navigates to the equivalent page in the chosen
+ * version (same module, different version subdirectory). If the equivalent
+ * page doesn't exist (the symbol was added later or removed) it falls back
+ * to the version's API root.
+ *
+ * Schema requirement for auto-discovery: your `src/content.config.ts`
+ * must accept these optional fields (the create-docs template already
+ * does):
+ *
+ *   docsSchema({
+ *     extend: z.object({
+ *       version: z.string().optional(),
+ *       versionLabel: z.string().optional(),
+ *       versionDefault: z.boolean().optional(),
+ *     }),
+ *   })
+ */
+import { getCollection } from 'astro:content';
+
+interface Version {
+  /** Git tag (used as the URL segment after the safeTag transform: `v0.3.0` → `0.3.0`). */
+  tag: string;
+  /** Human label shown in the dropdown (e.g. "0.3 (legacy)"). */
+  label?: string;
+  /** True for the version aliased to the un-versioned URL. */
+  default?: boolean;
+}
+
+interface Props {
+  /** Optional: override the auto-discovered list. Omit to use frontmatter-based discovery. */
+  versions?: Version[];
+  /** Base URL of the API reference (default `/api`). Match `outputDir` in autodoc config. */
+  apiBase?: string;
+}
+
+const { versions: propVersions, apiBase = '/api' } = Astro.props;
+const base = (import.meta.env.BASE_URL || '/').replace(/\/$/, '');
+
+// Match `safeTag()` in the autodoc scripts: strip leading `v`, then
+// replace dots and any other non-alphanumeric chars with `-`. Dots get
+// stripped by Astro's URL slug normalizer (`0.1.0` → `010`) so we use
+// dashes from the start to keep filesystem and URL byte-identical.
+function safeTag(tag: string): string {
+  return tag.replace(/^v/, '').replace(/[^a-zA-Z0-9_-]/g, '-');
+}
+
+// ─── Resolve the version list ─────────────────────────────────────────
+//
+// 1. Caller passed `versions` prop → use as-is.
+// 2. Otherwise, walk the docs collection looking for `version:` frontmatter
+//    fields written by the autodoc orchestrators. Dedupe, sort, mark default.
+// 3. If nothing turns up, leave `versions` empty and the component renders
+//    nothing (the `{currentTag &&` guard below short-circuits).
+let versions: Version[] = propVersions ?? [];
+if (!propVersions || propVersions.length === 0) {
+  try {
+    const all = await getCollection('docs');
+    const seen = new Map<string, Version>();
+    for (const entry of all) {
+      const data = entry.data as {
+        version?: string;
+        versionLabel?: string;
+        versionDefault?: boolean;
+      };
+      if (!data.version) continue;
+      const existing = seen.get(data.version);
+      // First occurrence wins for the tag/label; if any page in this
+      // version sets `versionDefault`, treat the version as default.
+      if (!existing) {
+        seen.set(data.version, {
+          tag: data.version,
+          label: data.versionLabel ?? data.version,
+          default: !!data.versionDefault,
+        });
+      } else if (data.versionDefault && !existing.default) {
+        existing.default = true;
+      }
+    }
+    versions = [...seen.values()];
+
+    // Sort: default first, then descending semver-ish. `localeCompare`
+    // with `numeric: true` handles `0.4.0` vs `0.10.0` correctly.
+    versions.sort((a, b) => {
+      if (a.default !== b.default) return a.default ? -1 : 1;
+      return b.tag.localeCompare(a.tag, 'en', { numeric: true });
+    });
+
+    // Fallback: if nothing was marked default, promote the first sorted
+    // entry. The autodoc orchestrators always emit `versionDefault: true`,
+    // so this only triggers if the user wired versions some other way.
+    if (versions.length > 0 && !versions.some((v) => v.default)) {
+      versions[0].default = true;
+    }
+  } catch {
+    // No `docs` collection or no version frontmatter — render nothing.
+    versions = [];
+  }
+}
+
+// ─── Detect current version from URL ──────────────────────────────────
+//   /api/0.3.0/auditkit_config/  → current = "0.3.0"
+//   /api/auditkit_config/        → current = default
+const path = Astro.url.pathname.replace(base, '');
+const apiPrefix = apiBase.replace(/\/$/, '') + '/';
+let currentTag: string | null = null;
+let currentPage: string | null = null;
+if (path.startsWith(apiPrefix)) {
+  const rest = path.slice(apiPrefix.length).replace(/\/$/, '');
+  const [first, ...remainder] = rest.split('/');
+  const matched = versions.find((v) => safeTag(v.tag) === first);
+  if (matched) {
+    currentTag = matched.tag;
+    currentPage = remainder.join('/');
+  } else {
+    const def = versions.find((v) => v.default);
+    if (def) {
+      currentTag = def.tag;
+      currentPage = rest;
+    }
+  }
+}
+---
+
+{currentTag && versions.length > 1 && (
+  <starlight-version-picker class="ad-version-picker" data-api-base={apiBase} data-current-page={currentPage ?? ''} data-base={base}>
+    <label>
+      <span class="sr-only">API version</span>
+      <select aria-label="API version">
+        {versions.map((v) => (
+          <option value={safeTag(v.tag)} selected={v.tag === currentTag} data-default={v.default ? 'true' : 'false'}>
+            {v.label ?? v.tag}
+          </option>
+        ))}
+      </select>
+    </label>
+  </starlight-version-picker>
+)}
+
+<style>
+  .ad-version-picker {
+    display: inline-flex;
+    align-items: center;
+    margin-inline-end: 0.75rem;
+  }
+  .ad-version-picker select {
+    appearance: none;
+    -webkit-appearance: none;
+    background: transparent;
+    color: var(--sl-color-white, var(--ad-cream));
+    border: 1px solid var(--sl-color-gray-5, var(--ad-cyan-deep));
+    border-radius: 999px;
+    padding: 0.125rem 1.75rem 0.125rem 0.75rem;
+    font: 600 0.75rem/1 var(--sl-font-system, ui-sans-serif), system-ui;
+    letter-spacing: 0.04em;
+    text-transform: uppercase;
+    cursor: pointer;
+    background-image: linear-gradient(45deg, transparent 50%, currentColor 50%),
+                      linear-gradient(135deg, currentColor 50%, transparent 50%);
+    background-position: calc(100% - 0.7rem) center, calc(100% - 0.4rem) center;
+    background-size: 5px 5px, 5px 5px;
+    background-repeat: no-repeat;
+    transition: border-color 0.18s ease, color 0.18s ease;
+  }
+  .ad-version-picker select:hover,
+  .ad-version-picker select:focus-visible {
+    border-color: var(--ad-cyan, #00d9ff);
+    color: var(--ad-cyan, #00d9ff);
+    outline: none;
+  }
+  .sr-only {
+    position: absolute;
+    width: 1px; height: 1px;
+    padding: 0; margin: -1px;
+    overflow: hidden; clip: rect(0, 0, 0, 0);
+    white-space: nowrap; border: 0;
+  }
+</style>
+
+<script>
+  // Custom element gives us a clean place to attach the change handler
+  // without inline scripts (CSP-friendly).
+  class StarlightVersionPicker extends HTMLElement {
+    connectedCallback() {
+      const select = this.querySelector('select');
+      if (!(select instanceof HTMLSelectElement)) return;
+      const apiBase = (this.dataset.apiBase || '/api').replace(/\/$/, '');
+      const currentPage = this.dataset.currentPage || '';
+      const base = this.dataset.base || '';
+      select.addEventListener('change', (e) => {
+        const value = (e.target as HTMLSelectElement).value;
+        const option = (e.target as HTMLSelectElement).selectedOptions[0];
+        const isDefault = option?.dataset.default === 'true';
+        // Default version's pages live at the un-versioned URL.
+        const versionSegment = isDefault ? '' : `/${value}`;
+        const target = `${base}${apiBase}${versionSegment}/${currentPage}`.replace(/\/+$/, '/');
+        // First try the equivalent page in the chosen version. If it 404s
+        // we want to fall back to that version's index — but we can't
+        // detect 404 from a navigation, so trust the build: if the page
+        // exists for one version it usually exists for adjacent ones.
+        window.location.href = target;
+      });
+    }
+  }
+  if (!customElements.get('starlight-version-picker')) {
+    customElements.define('starlight-version-picker', StarlightVersionPicker);
+  }
+</script>

package/src/index.ts

@@ -36,6 +36,21 @@ export interface AbstractDataThemeConfig {
    * `expressiveCode.themes` in `astro.config.mjs`.
    */
   shiki?: boolean;
+
+  /**
+   * Base URL of the API reference for the bundled `<VersionPicker>`.
+   * Match `outputDir` in your autodoc JSON config (relative to
+   * `src/content/docs/`). Defaults to `/api`.
+   *
+   * The picker auto-discovers the version list from the docs collection's
+   * `version:` frontmatter (written by the autodoc orchestrator), so you
+   * don't need to maintain a separate version array — point this at the
+   * correct base path and the rest is automatic.
+   *
+   * @example "/api"          // python-autodoc.json: "outputDir": "src/content/docs/api"
+   * @example "/api/ts"       // ts-autodoc.json:    "outputDir": "src/content/docs/api/ts"
+   */
+  apiBase?: string;
 }
 
 const PLUGIN_NAME = '@abstractdata/starlight-theme';
@@ -62,8 +77,9 @@ export default function abstractDataTheme(
   const credit = opts.credit ?? 'auto';
   const version = opts.version ?? null;
   const shiki = opts.shiki ?? true;
+  const apiBase = opts.apiBase ?? '/api';
 
-  const runtimeConfig = JSON.stringify({ motion, credit, version });
+  const runtimeConfig = JSON.stringify({ motion, credit, version, apiBase });
 
   return {
     name: PLUGIN_NAME,