starlight-theme-celestia 0.2.4 → 0.3.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "starlight-theme-celestia",
   "type": "module",
-  "version": "0.2.4",
+  "version": "0.3.0",
   "description": "A clean, modern theme for Astro Starlight",
   "license": "MIT",
   "repository": {
@@ -29,7 +29,6 @@
     "@aria-ui/core": "^0.2.0",
     "@aria-ui/utils": "^0.1.5",
     "@fontsource/inter": "^5.0.0",
-    "@lorenzo_lewis/starlight-utils": "^0.3.0",
     "@pagefind/default-ui": "^1.5.2",
     "@shikijs/transformers": "^4.0.2",
     "@shikijs/twoslash": "^4.0.2",
@@ -42,19 +41,23 @@
     "starlight-versions": "^0.9.0"
   },
   "peerDependencies": {
-    "@astrojs/starlight": "*"
+    "@astrojs/starlight": "*",
+    "typescript": "^5.5.0 || ^6.0.0"
   },
   "peerDependenciesMeta": {
     "@astrojs/starlight": {
       "optional": true
+    },
+    "typescript": {
+      "optional": true
     }
   },
   "devDependencies": {
-    "@astrojs/starlight": "^0.39.0",
+    "@astrojs/starlight": "^0.41.0",
     "@tailwindcss/cli": "^4.2.2",
     "@tailwindcss/vite": "^4.2.2",
-    "@types/node": "^25.0.0",
-    "astro": "^6.1.6",
+    "@types/node": "^26.0.0",
+    "astro": "^7.0.2",
     "tailwindcss": "^4.2.2",
     "typescript": "^6.0.0"
   }

package/src/components/MultiSidebarPanel.astro

@@ -0,0 +1,18 @@
+---
+/**
+ * Renders one sidebar of a multi-sidebar setup.
+ *
+ * Starlight's default `Sidebar` reads `Astro.locals.starlightRoute.sidebar` and takes no props, so
+ * the entries of the sidebar being rendered are assigned onto the route data first.
+ */
+import Default from "@astrojs/starlight/components/Sidebar.astro";
+import type { StarlightRouteData } from "@astrojs/starlight/route-data";
+
+interface Props {
+  sidebar: StarlightRouteData["sidebar"];
+}
+
+Astro.locals.starlightRoute.sidebar = Astro.props.sidebar;
+---
+
+<Default />

package/src/components/MultiSidebarSelect.astro

@@ -0,0 +1,72 @@
+---
+/**
+ * `dropdown` switcher: a compact select listing every sidebar.
+ */
+import { Icon } from "@astrojs/starlight/components";
+
+import type { MultiSidebarGroup } from "./multi-sidebar";
+
+interface Props {
+  groups: MultiSidebarGroup[];
+}
+
+const { groups } = Astro.props;
+---
+
+<label>
+  <span class="sr-only">{Astro.locals.t("sidebarNav.accessibleLabel")}</span>
+  <select autocomplete="off">
+    {
+      groups.map((group) => (
+        <option value={group.panelId} selected={group.isCurrent}>
+          {group.label}
+        </option>
+      ))
+    }
+  </select>
+  <Icon name="down-caret" class="caret-icon" />
+</label>
+
+<style>
+  label {
+    --celestia-multi-sidebar-caret-size: 1rem;
+
+    position: relative;
+    display: flex;
+    align-items: center;
+    margin-block-end: 0.75rem;
+    color: var(--sl-color-gray-2);
+  }
+
+  label:hover {
+    color: var(--sl-color-white);
+  }
+
+  .caret-icon {
+    position: absolute;
+    top: 50%;
+    inset-inline-end: 0.5rem;
+    transform: translateY(-50%);
+    pointer-events: none;
+    font-size: var(--celestia-multi-sidebar-caret-size);
+  }
+
+  select {
+    appearance: none;
+    width: 100%;
+    background-color: var(--sl-color-gray-6);
+    border: 0;
+    border-radius: 0.375rem;
+    color: inherit;
+    cursor: pointer;
+    font-size: var(--sl-text-sm);
+    padding-block: 0.35rem;
+    padding-inline: 0.5rem calc(var(--celestia-multi-sidebar-caret-size) + 0.5rem);
+    text-overflow: ellipsis;
+  }
+
+  option {
+    background-color: var(--sl-color-black);
+    color: var(--sl-color-gray-1);
+  }
+</style>

package/src/components/MultiSidebarTabs.astro

@@ -0,0 +1,84 @@
+---
+/**
+ * `horizontalList` switcher: one tab per sidebar, rendered above the sidebar entries.
+ */
+import { Badge } from "@astrojs/starlight/components";
+
+import type { MultiSidebarGroup } from "./multi-sidebar";
+
+interface Props {
+  groups: MultiSidebarGroup[];
+}
+
+const { groups } = Astro.props;
+---
+
+<div class="tablist-wrapper celestia-scroll-container not-content">
+  <ul role="tablist">
+    {
+      groups.map((group) => (
+        <li role="presentation">
+          <a
+            role="tab"
+            id={group.tabId}
+            href={`#${group.panelId}`}
+            aria-selected={group.isCurrent ? "true" : "false"}
+            aria-controls={group.panelId}
+            tabindex={group.isCurrent ? 0 : -1}
+          >
+            <span>{group.label}</span>
+            {group.badge && (
+              <Badge variant={group.badge.variant} class={group.badge.class} text={group.badge.text} />
+            )}
+          </a>
+        </li>
+      ))
+    }
+  </ul>
+</div>
+
+<style>
+  .tablist-wrapper {
+    margin-block-end: 0.75rem;
+    overflow-x: auto;
+  }
+
+  [role="tablist"] {
+    display: grid;
+    grid-auto-flow: column;
+    grid-auto-columns: 1fr;
+    list-style: none;
+    margin: 0;
+    padding: 0;
+  }
+
+  [role="tab"] {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    gap: 0.25em;
+    /*
+     * `ThemeProvider` already underlines every tab of the theme with `!important`, so this only
+     * matters if that global styling is ever dropped.
+     */
+    box-shadow: inset 0 -1px 0 var(--sl-color-gray-5);
+    padding: 0.25rem 0.5rem 0.4rem;
+    color: var(--sl-color-gray-3);
+    font-size: var(--sl-text-sm);
+    line-height: 1.4;
+    text-align: center;
+    text-decoration: none;
+    white-space: nowrap;
+  }
+
+  [role="tab"]:hover,
+  [role="tab"]:focus-visible {
+    color: var(--sl-color-white);
+  }
+
+  [role="tab"][aria-selected="true"] {
+    box-shadow: inset 0 -2px 0 var(--sl-color-accent-high);
+    color: var(--sl-color-white);
+    font-weight: 600;
+  }
+</style>

package/src/components/Sidebar.astro

@@ -0,0 +1,121 @@
+---
+/**
+ * Multi-sidebar `Sidebar` override.
+ *
+ * Registered by the theme only when the `multiSidebar` option is set. It renders one switchable
+ * sidebar per top-level group of the Starlight `sidebar` config, replacing
+ * `@lorenzo_lewis/starlight-utils`, which is deprecated on npm.
+ */
+import config from "virtual:starlight-theme-celestia/user-config";
+
+import MultiSidebarPanel from "./MultiSidebarPanel.astro";
+import MultiSidebarSelect from "./MultiSidebarSelect.astro";
+import MultiSidebarTabs from "./MultiSidebarTabs.astro";
+import { getMultiSidebarGroups } from "./multi-sidebar";
+
+const switcherStyle = config.multiSidebar?.switcherStyle ?? "horizontalList";
+const groups = getMultiSidebarGroups(Astro.locals.starlightRoute.sidebar);
+
+// Without a switcher there is nothing to switch to, so the other sidebars are never rendered.
+const panels = switcherStyle === "hidden" ? groups.filter(({ isCurrent }) => isCurrent) : groups;
+---
+
+<celestia-multi-sidebar>
+  {switcherStyle === "horizontalList" && <MultiSidebarTabs groups={groups} />}
+  {switcherStyle === "dropdown" && <MultiSidebarSelect groups={groups} />}
+  {
+    panels.map((group) =>
+      switcherStyle === "horizontalList" ? (
+        <section id={group.panelId} role="tabpanel" aria-labelledby={group.tabId} hidden={!group.isCurrent}>
+          <MultiSidebarPanel sidebar={group.entries} />
+        </section>
+      ) : (
+        <section id={group.panelId} aria-label={group.label} hidden={!group.isCurrent}>
+          <MultiSidebarPanel sidebar={group.entries} />
+        </section>
+      ),
+    )
+  }
+</celestia-multi-sidebar>
+
+<style>
+  /*
+   * The switcher and the sidebars have to sit in the sidebar flex column of `PageFrame`, so the
+   * custom element adds no box of its own and the selected sidebar reproduces that column for the
+   * entries it wraps. `hidden` still wins for the sidebars that are not selected, because the rule
+   * below only applies to the selected one.
+   */
+  celestia-multi-sidebar {
+    display: contents;
+  }
+
+  section:not([hidden]) {
+    display: flex;
+    flex: 1;
+    flex-direction: column;
+    min-height: max-content;
+  }
+</style>
+
+<script>
+  class CelestiaMultiSidebar extends HTMLElement {
+    #panels: HTMLElement[];
+    #tabs: HTMLAnchorElement[];
+
+    constructor() {
+      super();
+
+      this.#panels = [...this.querySelectorAll<HTMLElement>(":scope > section")];
+      this.#tabs = [...this.querySelectorAll<HTMLAnchorElement>('[role="tab"]')];
+
+      for (const [index, tab] of this.#tabs.entries()) {
+        tab.addEventListener("click", (event) => {
+          event.preventDefault();
+          this.#select(index);
+        });
+
+        tab.addEventListener("keydown", (event) => {
+          const nextIndex =
+            event.key === "ArrowLeft"
+              ? index - 1
+              : event.key === "ArrowRight"
+                ? index + 1
+                : event.key === "Home"
+                  ? 0
+                  : event.key === "End"
+                    ? this.#tabs.length - 1
+                    : null;
+
+          if (nextIndex === null || !this.#tabs[nextIndex]) return;
+
+          event.preventDefault();
+          this.#select(nextIndex);
+          this.#tabs[nextIndex]?.focus();
+        });
+      }
+
+      const select = this.querySelector("select");
+      select?.addEventListener("change", () => {
+        this.#select(this.#panels.findIndex((panel) => panel.id === select.value));
+      });
+    }
+
+    #select(index: number) {
+      if (index < 0) return;
+
+      for (const [panelIndex, panel] of this.#panels.entries()) {
+        panel.hidden = panelIndex !== index;
+      }
+
+      for (const [tabIndex, tab] of this.#tabs.entries()) {
+        const isSelected = tabIndex === index;
+        tab.setAttribute("aria-selected", isSelected ? "true" : "false");
+        tab.setAttribute("tabindex", isSelected ? "0" : "-1");
+      }
+    }
+  }
+
+  if (!customElements.get("celestia-multi-sidebar")) {
+    customElements.define("celestia-multi-sidebar", CelestiaMultiSidebar);
+  }
+</script>

package/src/components/multi-sidebar.test.ts

@@ -0,0 +1,47 @@
+import type { StarlightRouteData } from "@astrojs/starlight/route-data";
+import { expect, test } from "bun:test";
+
+import { getMultiSidebarGroups } from "./multi-sidebar";
+
+type SidebarEntry = StarlightRouteData["sidebar"][number];
+
+function link(label: string, isCurrent = false): SidebarEntry {
+  return { type: "link", label, href: `/${label}/`, isCurrent, badge: undefined, attrs: {} };
+}
+
+function group(label: string, entries: SidebarEntry[]): SidebarEntry {
+  return { type: "group", label, entries: entries as never, collapsed: false, badge: undefined };
+}
+
+test("every top-level group becomes a sidebar", () => {
+  const groups = getMultiSidebarGroups([group("Guide", [link("start")]), group("Reference", [link("config")])]);
+
+  expect(groups.map(({ label }) => label)).toEqual(["Guide", "Reference"]);
+  expect(groups.map(({ tabId }) => tabId)).toEqual(["celestia-sidebar-tab-0", "celestia-sidebar-tab-1"]);
+  expect(groups.map(({ panelId }) => panelId)).toEqual(["celestia-sidebar-panel-0", "celestia-sidebar-panel-1"]);
+});
+
+test("the sidebar holding the current page is selected, however deeply it is nested", () => {
+  const groups = getMultiSidebarGroups([
+    group("Guide", [link("start")]),
+    group("Reference", [group("Nested", [group("Deeper", [link("config", true)])])]),
+  ]);
+
+  expect(groups.map(({ isCurrent }) => isCurrent)).toEqual([false, true]);
+});
+
+test("pages outside every sidebar fall back to the first one", () => {
+  const groups = getMultiSidebarGroups([group("Guide", [link("start")]), group("Reference", [link("config")])]);
+
+  expect(groups.map(({ isCurrent }) => isCurrent)).toEqual([true, false]);
+});
+
+test("a top-level entry that is not a group is rejected", () => {
+  expect(() => getMultiSidebarGroups([group("Guide", [link("start")]), link("Blog")])).toThrow(
+    /`Blog` cannot be used with multi-sidebar/,
+  );
+});
+
+test("an empty sidebar yields no sidebars", () => {
+  expect(getMultiSidebarGroups([])).toEqual([]);
+});

package/src/components/multi-sidebar.ts

@@ -0,0 +1,64 @@
+import type { StarlightRouteData } from "@astrojs/starlight/route-data";
+import { AstroError } from "astro/errors";
+
+type SidebarEntry = StarlightRouteData["sidebar"][number];
+type SidebarGroup = Extract<SidebarEntry, { type: "group" }>;
+
+export interface MultiSidebarGroup {
+  /** Label of the top-level group backing this sidebar. */
+  label: string;
+  /** Optional badge rendered next to the label in the switcher. */
+  badge: SidebarGroup["badge"];
+  /** Entries rendered when this sidebar is selected. */
+  entries: SidebarEntry[];
+  /** Whether this sidebar contains the page being rendered. */
+  isCurrent: boolean;
+  /** DOM id of the switcher control for this sidebar. */
+  tabId: string;
+  /** DOM id of the panel holding this sidebar's entries. */
+  panelId: string;
+}
+
+/** Recursively check whether a sidebar entry contains the page being rendered. */
+function containsCurrentPage(entry: SidebarEntry): boolean {
+  return entry.type === "link" ? entry.isCurrent : entry.entries.some(containsCurrentPage);
+}
+
+/**
+ * Turn the route's sidebar into one switchable sidebar per top-level group.
+ *
+ * Unlike `@lorenzo_lewis/starlight-utils`, this runs while the `Sidebar` component renders instead
+ * of in a route middleware, so it always sees the sidebar every other plugin has finished building.
+ * That matters for `starlight-versions`, whose middleware narrows the sidebar to the current
+ * version and cannot be ordered against a second sidebar-rewriting middleware.
+ */
+export function getMultiSidebarGroups(sidebar: StarlightRouteData["sidebar"]): MultiSidebarGroup[] {
+  const groups = sidebar.map((entry, index) => {
+    if (entry.type !== "group") {
+      throw new AstroError(
+        `\`${entry.label}\` cannot be used with multi-sidebar.`,
+        "Each top-level `sidebar` item in the Starlight config must be a group or autogenerated when the " +
+          "`multiSidebar` option of `starlight-theme-celestia` is enabled.\n" +
+          "See https://starlight.astro.build/guides/sidebar/#groups and " +
+          "https://starlight.astro.build/guides/sidebar/#autogenerated-groups for more details.",
+      );
+    }
+
+    return {
+      label: entry.label,
+      badge: entry.badge,
+      entries: entry.entries,
+      isCurrent: containsCurrentPage(entry),
+      tabId: `celestia-sidebar-tab-${index}`,
+      panelId: `celestia-sidebar-panel-${index}`,
+    };
+  });
+
+  // Pages outside every sidebar, such as the site index, fall back to the first sidebar.
+  const first = groups[0];
+  if (first && !groups.some((group) => group.isCurrent)) {
+    first.isCurrent = true;
+  }
+
+  return groups;
+}

package/src/index.test.ts

@@ -1,6 +1,36 @@
+import type { StarlightPlugin, StarlightUserConfig } from "@astrojs/starlight/types";
 import { expect, test } from "bun:test";
 
 import starlightCelestiaTheme from "./index";
+import type { ThemeCelestiaOptions } from "./user-options";
+
+type ConfigSetupHook = NonNullable<StarlightPlugin["hooks"]["config:setup"]>;
+type ConfigSetupOptions = Parameters<ConfigSetupHook>[0];
+
+/** Run the `config:setup` hook of the theme and return the config it asks Starlight to apply. */
+async function setupConfig(
+  options: ThemeCelestiaOptions = {},
+  components: StarlightUserConfig["components"] = {},
+): Promise<Partial<StarlightUserConfig>> {
+  const hook = starlightCelestiaTheme(options).hooks["config:setup"];
+
+  if (!hook) {
+    throw new Error("the theme no longer registers a `config:setup` hook");
+  }
+
+  let updated: Partial<StarlightUserConfig> = {};
+
+  await hook({
+    config: { components },
+    updateConfig: (config: Partial<StarlightUserConfig>) => {
+      updated = config;
+    },
+    addIntegration: () => {},
+    astroConfig: { root: new URL("file:///project/"), vite: {} },
+  } as unknown as ConfigSetupOptions);
+
+  return updated;
+}
 
 test("default factory returns a valid Starlight plugin", () => {
   const plugin = starlightCelestiaTheme();
@@ -9,3 +39,21 @@ test("default factory returns a valid Starlight plugin", () => {
   expect(plugin.hooks).toHaveProperty("config:setup");
   expect(typeof plugin.hooks["config:setup"]).toBe("function");
 });
+
+test("Starlight's own sidebar is kept when multi-sidebar is not configured", async () => {
+  const config = await setupConfig();
+
+  expect(config.components).not.toHaveProperty("Sidebar");
+});
+
+test("the sidebar is overridden when multi-sidebar is configured", async () => {
+  const config = await setupConfig({ multiSidebar: { switcherStyle: "dropdown" } });
+
+  expect(config.components?.Sidebar).toBe("starlight-theme-celestia/components/Sidebar.astro");
+});
+
+test("a user override of the sidebar wins over the multi-sidebar one", async () => {
+  const config = await setupConfig({ multiSidebar: {} }, { Sidebar: "./src/components/Sidebar.astro" });
+
+  expect(config.components?.Sidebar).toBe("./src/components/Sidebar.astro");
+});

package/src/index.ts

@@ -3,7 +3,7 @@ import type { AstroConfig } from "astro";
 import remarkCustomHeaderId from "remark-custom-header-id";
 
 import { createShikiConfig } from "./shiki-config";
-import type { ThemeCelestiaOptions } from "./user-options";
+import type { MultiSidebarOptions, ThemeCelestiaOptions } from "./user-options";
 import { vitePluginUserConfig } from "./virtual-user-config";
 
 const components = {
@@ -25,7 +25,9 @@ const components = {
   Head: "starlight-theme-celestia/components/Head.astro",
 } as const satisfies Partial<StarlightConfig["components"]>;
 
-export type { ThemeCelestiaOptions };
+const sidebarComponent = "starlight-theme-celestia/components/Sidebar.astro";
+
+export type { MultiSidebarOptions, ThemeCelestiaOptions };
 
 export default function starlightCelestiaTheme(options: ThemeCelestiaOptions = {}): StarlightPlugin {
   return {
@@ -57,6 +59,9 @@ export default function starlightCelestiaTheme(options: ThemeCelestiaOptions = {
           ].filter(Boolean),
           components: {
             ...components,
+            // Only override the sidebar when multi-sidebar is enabled, so Starlight's default keeps
+            // rendering for every other site.
+            ...(options.multiSidebar ? { Sidebar: sidebarComponent } : {}),
             ...config.components,
           },
           expressiveCode: config.expressiveCode ?? false,
@@ -77,6 +82,7 @@ export default function starlightCelestiaTheme(options: ThemeCelestiaOptions = {
                   plugins: [
                     vitePluginUserConfig({
                       nav: options.nav,
+                      multiSidebar: options.multiSidebar,
                       rootHref: astroConfig.root.toString(),
                     }),
                   ],

package/src/shiki-config.test.ts

@@ -0,0 +1,22 @@
+import { expect, test } from "bun:test";
+
+import { createShikiConfig, isTwoslashCompatibleTsModule } from "./shiki-config";
+
+test("a TypeScript module exposing the Node system API is usable for Twoslash", () => {
+  expect(isTwoslashCompatibleTsModule({ sys: { readFile: () => undefined } })).toBe(true);
+});
+
+test("a missing or incompatible TypeScript module is rejected", () => {
+  expect(isTwoslashCompatibleTsModule(undefined)).toBe(false);
+  expect(isTwoslashCompatibleTsModule(null)).toBe(false);
+  // TypeScript 7 ships a native compiler without the `ts.sys` API.
+  expect(isTwoslashCompatibleTsModule({ version: "7.0.2" })).toBe(false);
+  expect(isTwoslashCompatibleTsModule({ sys: {} })).toBe(false);
+});
+
+test("the Twoslash transformer is only added when requested", () => {
+  const withTwoslash = createShikiConfig({ twoslash: true }).transformers ?? [];
+  const withoutTwoslash = createShikiConfig({ twoslash: false }).transformers ?? [];
+
+  expect(withTwoslash.length).toBe(withoutTwoslash.length + 1);
+});

package/src/shiki-config.ts

@@ -9,10 +9,13 @@ import {
 import { transformerTwoslash } from "@shikijs/twoslash";
 import type { ShikiTransformer } from "@shikijs/types";
 import type { ShikiConfig } from "astro";
+import { createRequire } from "node:module";
 import { createRenderer } from "shiki-twoslash-renderer";
 
 import { transformerContainer } from "./shiki-transformer-container";
 
+const require = createRequire(import.meta.url);
+
 export function createShikiConfig(options: { twoslash: boolean }): ShikiConfig {
   const transformers: ShikiTransformer[] = [
     transformerMetaHighlight(),
@@ -23,19 +26,7 @@ export function createShikiConfig(options: { twoslash: boolean }): ShikiConfig {
     transformerRemoveNotationEscape(),
 
     transformerContainer(),
-    ...(options.twoslash
-      ? [
-          transformerTwoslash({
-            renderer: createRenderer(),
-            explicitTrigger: true,
-            twoslashOptions: {
-              compilerOptions: {
-                noUncheckedSideEffectImports: false,
-              },
-            },
-          }),
-        ]
-      : []),
+    ...(options.twoslash ? createTwoslashTransformers() : []),
   ];
 
   return {
@@ -47,3 +38,50 @@ export function createShikiConfig(options: { twoslash: boolean }): ShikiConfig {
     transformers: transformers,
   };
 }
+
+/**
+ * Twoslash needs the Node API surface of TypeScript, `ts.sys` in particular.
+ * Projects that do not pin `typescript` themselves can end up with the native
+ * TypeScript 7 package, which does not expose that API, so probe the resolved
+ * module before handing it to Twoslash.
+ *
+ * @internal
+ */
+export function isTwoslashCompatibleTsModule(tsModule: unknown): boolean {
+  const sys = (tsModule as { sys?: { readFile?: unknown } } | null | undefined)?.sys;
+
+  return typeof sys?.readFile === "function";
+}
+
+type TwoslashOptions = NonNullable<NonNullable<Parameters<typeof transformerTwoslash>[0]>["twoslashOptions"]>;
+
+function createTwoslashTransformers(): ShikiTransformer[] {
+  let tsModule: unknown;
+
+  try {
+    tsModule = require("typescript");
+  } catch {
+    tsModule = undefined;
+  }
+
+  if (!isTwoslashCompatibleTsModule(tsModule)) {
+    console.warn(
+      "[starlight-theme-celestia] Twoslash code blocks are disabled because no compatible `typescript` installation was found. Add `typescript` (^5.5.0 || ^6.0.0) to your project to enable them.",
+    );
+
+    return [];
+  }
+
+  return [
+    transformerTwoslash({
+      renderer: createRenderer(),
+      explicitTrigger: true,
+      twoslashOptions: {
+        tsModule: tsModule as TwoslashOptions["tsModule"],
+        compilerOptions: {
+          noUncheckedSideEffectImports: false,
+        },
+      },
+    }),
+  ];
+}