starlight-sidebar-topics-dropdown 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # starlight-sidebar-topics-dropdown
 
+## 0.4.0
+
+### Minor Changes
+
+- [#31](https://github.com/trueberryless-org/starlight-sidebar-topics-dropdown/pull/31) [`3193771`](https://github.com/trueberryless-org/starlight-sidebar-topics-dropdown/commit/31937716171b020f414ece6783c17181fbd5fdcf) Thanks [@trueberryless](https://github.com/trueberryless)! - ⚠️ **BREAKING CHANGE:** The Starlight Sidebar Topics Dropdown plugin no longer provides the same ["Unnested Sidebar" configuration](https://starlight-sidebar-topics-dropdown.trueberryless.org/docs/guides/unnested-sidebar/) like before. Please adapt your `astro.config.mjs` with the up-to-date guide on [how to configure a "Unnested Sidebar"](https://starlight-sidebar-topics-dropdown.trueberryless.org/docs/guides/unnested-sidebar/#configure-an-unnested-sidebar).
+
+- [#31](https://github.com/trueberryless-org/starlight-sidebar-topics-dropdown/pull/31) [`db10526`](https://github.com/trueberryless-org/starlight-sidebar-topics-dropdown/commit/db10526d49aab3ac8619159d40968dbc4748c9a0) Thanks [@trueberryless](https://github.com/trueberryless)! - ⚠️ **BREAKING CHANGE:** The minimum supported version of Starlight is now version `0.32.0`.
+
+  Please use the `@astrojs/upgrade` command to upgrade your project:
+
+  ```sh
+  npx @astrojs/upgrade
+  ```
+
+- [#31](https://github.com/trueberryless-org/starlight-sidebar-topics-dropdown/pull/31) [`db10526`](https://github.com/trueberryless-org/starlight-sidebar-topics-dropdown/commit/db10526d49aab3ac8619159d40968dbc4748c9a0) Thanks [@trueberryless](https://github.com/trueberryless)! - ⚠️ **BREAKING CHANGE:** The Starlight Sidebar Topics Dropdown plugin no longer [overrides](https://starlight.astro.build/guides/overriding-components/) the [`<Pagination>` component](https://starlight.astro.build/reference/overrides/#pagination). If you were manually rendering `starlight-sidebar-topics-dropdown/overrides/Pagination.astro` in a custom override, you can now remove it.
+
 ## 0.3.0
 
 ### Minor Changes

package/components/Topics.astro

@@ -6,7 +6,7 @@ import { getRelativeLocaleUrl } from 'astro:i18n'
 import starlightConfig from 'virtual:starlight/user-config'
 import config from 'virtual:starlight-sidebar-topics-dropdown/config'
 
-import type { StarlightSidebarTopicsDropdownSharedConfig } from '../lib/config'
+import type { StarlightSidebarTopicsDropdownSharedConfig } from '../libs/config'
 
 interface Props {
   current: StarlightSidebarTopicsDropdownSharedConfig[number]
@@ -98,9 +98,9 @@ function getTranslation(translations: Record<string, string>, link: string, desc
   .starlight-sidebar-topics-dropdown-dropdown {
     position: relative;
     display: block;
-    width: calc(100% - 8px - 2 * 2px);
-    margin-left: calc(8px + 2px);
-    margin-right: calc(2px);
+    width: calc(100% - 2 * 2px);
+    margin-inline: 2px;
+		margin-top: 4px;
   }
 
   .starlight-sidebar-topics-dropdown-button {

package/components/starlight/Sidebar.astro

@@ -0,0 +1,28 @@
+---
+import { StarlightSidebarTopicsDropdownLocalsSymbol, type StarlightSidebarTopicsDropdownLocals } from '../../libs/locals'
+import Topics from '../Topics.astro'
+const { entry } = Astro.locals.starlightRoute
+// @ts-expect-error - See `libs/locals` for more information.
+const currentTopic = Astro.locals[StarlightSidebarTopicsDropdownLocalsSymbol] as StarlightSidebarTopicsDropdownLocals
+---
+
+{entry['data'].template !== 'splash' && currentTopic && <Topics current={currentTopic.config} />}
+
+<style is:global>
+	sl-sidebar-state-persist ul.top-level > li:not(:has(details)) {
+		margin-top: 0rem;
+	}
+	sl-sidebar-state-persist ul.top-level > li:has(details) {
+		margin-block: 0.5rem;
+	}
+	/* sl-sidebar-state-persist ul.top-level > li > a {
+		font-size: var(--sl-text-sm);
+	} */
+	sl-sidebar-state-persist ul.top-level > li > a[aria-current='page'] {
+		font-weight: 600;
+	}
+	sl-sidebar-state-persist ul.top-level > li > a[aria-current='false'] {
+		font-weight: 400;
+		color: var(--sl-color-gray-2);
+	}
+</style>

package/index.ts

@@ -6,14 +6,14 @@ import type {
 import {
   StarlightSidebarTopicsDropdownConfigSchema,
   type StarlightSidebarTopicsDropdownUserConfig,
-} from "./lib/config";
-import { overrideStarlightComponent, throwPluginError } from "./lib/plugin";
-import { vitePluginStarlightSidebarTopicsDropdown } from "./lib/vite";
+} from "./libs/config";
+import { overrideStarlightComponent, throwPluginError } from "./libs/plugin";
+import { vitePluginStarlightSidebarTopicsDropdown } from "./libs/vite";
 
 export type {
   StarlightSidebarTopicsDropdownConfig,
   StarlightSidebarTopicsDropdownUserConfig,
-} from "./lib/config";
+} from "./libs/config";
 
 export default function starlightSidebarTopicsDropdownPlugin(
   userConfig: StarlightSidebarTopicsDropdownUserConfig
@@ -34,8 +34,9 @@ export default function starlightSidebarTopicsDropdownPlugin(
   return {
     name: "starlight-sidebar-topics-dropdown-plugin",
     hooks: {
-      setup({
+      "config:setup"({
         addIntegration,
+        addRouteMiddleware,
         command,
         config: starlightConfig,
         logger,
@@ -46,10 +47,14 @@ export default function starlightSidebarTopicsDropdownPlugin(
         if (starlightConfig.sidebar) {
           throwPluginError(
             "It looks like you have a `sidebar` configured in your Starlight configuration. To use `starlight-sidebar-topics-dropdown`, create a new topic with your sidebar items.",
-            "Learn more about topic configuration at https://starlight-sidebar-topics-dropdown.netlify.app/docs/configuration/"
+            "Learn more about topic configuration at https://starlight-sidebar-topics-dropdown.trueberryless.org/docs/configuration/"
           );
         }
 
+        addRouteMiddleware({
+          entrypoint: "starlight-sidebar-topics-dropdown/middleware",
+        });
+
         const sidebar: StarlightUserConfig["sidebar"] = [];
 
         for (const [index, topic] of config.entries()) {
@@ -65,11 +70,6 @@ export default function starlightSidebarTopicsDropdownPlugin(
               logger,
               "Sidebar"
             ),
-            ...overrideStarlightComponent(
-              starlightConfig.components,
-              logger,
-              "Pagination"
-            ),
           },
           sidebar,
         });

package/{lib → libs}/content.ts

@@ -1,4 +1,4 @@
-import type { Props } from "@astrojs/starlight/props";
+import type { StarlightRouteData } from "@astrojs/starlight/route-data";
 import type { TopicFrontmatterSchema } from "../schema";
 export function isStarlightEntryWithTopic(
   entry: StarlightEntry
@@ -9,7 +9,7 @@ export function isStarlightEntryWithTopic(
     typeof (entry as StarlightEntryWithTopic).data.topic === "string"
   );
 }
-export type StarlightEntry = Props["entry"];
+export type StarlightEntry = StarlightRouteData["entry"];
 export type StarlightEntryWithTopic = StarlightEntry & {
   data: TopicFrontmatterSchema;
 };

package/libs/locals.ts

@@ -0,0 +1,14 @@
+import type { StarlightSidebarTopicsDropdownSharedConfig } from "./config";
+
+/**
+ * We keep track of the current topic configuration using a variable stored using `Astro.locals` which will be reset for
+ * each new page. The value is tracked using an untyped symbol on purpose to avoid users to get autocomplete for it and
+ * avoid potential clashes with user-defined variables.
+ */
+export const StarlightSidebarTopicsDropdownLocalsSymbol = Symbol.for(
+  "starlight-sidebar-topics-dropdown:locals"
+);
+
+export interface StarlightSidebarTopicsDropdownLocals {
+  config: StarlightSidebarTopicsDropdownSharedConfig[number];
+}

package/{lib → libs}/plugin.ts

@@ -6,7 +6,7 @@ export function throwPluginError(message: string, hint?: string): never {
   throw new AstroError(
     message,
     hint ??
-      `See the error report above for more informations.\n\nIf you believe this is a bug, please file an issue at https://github.com/HiDeoo/starlight-sidebar-topics-dropdown/issues/new/choose`
+      `See the error report above for more informations.\n\nIf you believe this is a bug, please file an issue at https://github.com/trueberryless-org/starlight-sidebar-topics-dropdown/issues/new/choose`
   );
 }
 

package/{lib → libs}/sidebar.ts

@@ -1,4 +1,4 @@
-import type { Props } from "@astrojs/starlight/props";
+import type { StarlightRouteData } from "@astrojs/starlight/route-data";
 
 import type { StarlightSidebarTopicsDropdownSharedConfig } from "./config";
 import { isStarlightEntryWithTopic, type StarlightEntry } from "./content";
@@ -196,7 +196,7 @@ function getTopicIdFromEntry(entry: StarlightEntry): string | undefined {
   return isStarlightEntryWithTopic(entry) ? entry.data.topic : undefined;
 }
 
-type SidebarEntry = Props["sidebar"][number];
+type SidebarEntry = StarlightRouteData["sidebar"][number];
 
 interface SidebarTopic {
   label: string;

package/libs/starlight.ts

@@ -0,0 +1,29 @@
+import type { StarlightUserConfig } from "@astrojs/starlight/types";
+import type { AstroIntegrationLogger } from "astro";
+
+export function overrideStarlightComponent(
+  components: StarlightUserConfig["components"],
+  logger: AstroIntegrationLogger,
+  override: keyof NonNullable<StarlightUserConfig["components"]>,
+  component: string
+) {
+  if (components?.[override]) {
+    logger.warn(
+      `It looks like you already have a \`${override}\` component override in your Starlight configuration.`
+    );
+    logger.warn(
+      `To use \`starlight-sidebar-topics-dropdown\`, either remove your override or update it to render the content from \`starlight-sidebar-topics-dropdown/components/${component}.astro\`.`
+    );
+    // if (component === "DynamicVersionBadge") {
+    //   logger.warn(
+    //     "Notice that the `DynamicVersionBadge` component must be rendered AFTER the original Starlight `SiteTitle` component in the DOM. This ensures proper layout and behavior within the application."
+    //   );
+    // }
+
+    return {};
+  }
+
+  return {
+    [override]: `starlight-sidebar-topics-dropdown/overrides/${override}.astro`,
+  };
+}

package/middleware.ts

@@ -0,0 +1,43 @@
+import { defineRouteMiddleware } from "@astrojs/starlight/route-data";
+import config from "virtual:starlight-sidebar-topics-dropdown/config";
+
+import {
+  StarlightSidebarTopicsDropdownLocalsSymbol,
+  type StarlightSidebarTopicsDropdownLocals,
+} from "./libs/locals";
+import { throwPluginError } from "./libs/plugin";
+import {
+  getCurrentTopic,
+  isTopicFirstPage,
+  isTopicLastPage,
+} from "./libs/sidebar";
+
+export const onRequest = defineRouteMiddleware((context) => {
+  const { starlightRoute } = context.locals;
+  const { entry, id, pagination, sidebar } = starlightRoute;
+
+  if (entry["data"].template !== "splash") {
+    const currentTopic = getCurrentTopic(config, sidebar, id, entry);
+
+    if (!currentTopic)
+      throwPluginError(
+        `Failed to find the topic for the \`${id}\` page.`,
+        `Either include this page in the sidebar configuration of the desired topic using the \`items\` property or to associate an unlisted page with a topic, use the \`topic\` frontmatter property and set it to the desired topic ID.
+  Learn more about unlisted pages in the ["Unlisted pages"](https://starlight-sidebar-topics-dropdown.trueberryless.org/docs/guides/unlisted-pages/) guide.`
+      );
+
+    starlightRoute.sidebar = currentTopic.sidebar;
+    // @ts-expect-error - See `libs/locals` for more information.
+    context.locals[StarlightSidebarTopicsDropdownLocalsSymbol] = {
+      config: currentTopic.config,
+    } satisfies StarlightSidebarTopicsDropdownLocals;
+
+    if (isTopicFirstPage(sidebar, id)) {
+      pagination.prev = undefined;
+    }
+
+    if (isTopicLastPage(sidebar, id)) {
+      pagination.next = undefined;
+    }
+  }
+});

package/overrides/Sidebar.astro

@@ -1,40 +1,7 @@
 ---
 import Default from '@astrojs/starlight/components/Sidebar.astro'
-import type { Props } from '@astrojs/starlight/props'
-import config from 'virtual:starlight-sidebar-topics-dropdown/config'
-
-import Topics from '../components/Topics.astro'
-import { throwPluginError } from '../lib/plugin'
-import { getCurrentTopic, type Topic } from '../lib/sidebar'
-
-const { id, entry, sidebar } = Astro.props
-
-let currentSidebar = sidebar
-let currentTopic: Topic | undefined = undefined
-
-if (entry['data'].template !== 'splash') {
-  currentTopic = getCurrentTopic(config, sidebar, id, entry)
-  if (!currentTopic)
-    throwPluginError(
-      `Failed to find the topic for the \`${id}\` page.`,
-      `Either include this page in the sidebar configuration of the desired topic using the \`items\` property or to associate an unlisted page with a topic, use the \`topic\` frontmatter property and set it to the desired topic ID.
-Learn more about unlisted pages in the ["Unlisted pages"](https://starlight-sidebar-topics.netlify.app/docs/guides/unlisted-pages/) guide.`,
-    )
-  currentSidebar = currentTopic.sidebar
-}
+import StarlightSidebarTopicsDropdownSidebar from '../components/starlight/Sidebar.astro'
 ---
 
-{entry['data'].template !== 'splash' && currentTopic && <Topics current={currentTopic.config} />}
-<Default {...Astro.props} sidebar={currentSidebar}><slot /></Default>
-
-{!currentTopic?.sidebarHasGroups &&
-  <style is:global>
-    sl-sidebar-state-persist summary {
-      display: none !important;
-    }
-    sl-sidebar-state-persist ul li {
-      margin-inline-start: 0;
-      border-inline-start: none;
-    }
-  </style>
-}
+<StarlightSidebarTopicsDropdownSidebar />
+<Default><slot /></Default>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "starlight-sidebar-topics-dropdown",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Starlight plugin to split your docs page into multiple subpages and switch between them with a dropdown menu in the sidebar.",
   "keywords": [
     "starlight",
@@ -24,14 +24,15 @@
   "type": "module",
   "exports": {
     ".": "./index.ts",
-    "./overrides/Pagination.astro": "./overrides/Pagination.astro",
+    "./components/Sidebar.astro": "./components/starlight/Sidebar.astro",
+    "./middleware": "./middleware.ts",
     "./overrides/Sidebar.astro": "./overrides/Sidebar.astro",
     "./schema": "./schema.ts",
     "./package.json": "./package.json"
   },
   "devDependencies": {
-    "@astrojs/starlight": "^0.30.3",
-    "astro": "^5.1.1"
+    "@astrojs/starlight": "^0.32.1",
+    "astro": "^5.3.0"
   },
   "peerDependencies": {
     "@astrojs/starlight": ">=0.30"

package/schema.ts

@@ -3,7 +3,7 @@ export const topicSchema = z.object({
   /**
    * ID of the topic to associate with the current page if the page is not listed in any topic sidebar configuration.
    *
-   * @see https://starlight-sidebar-topics.netlify.app/docs/guides/unlisted-pages/
+   * @see https://starlight-sidebar-topics-dropdown.trueberryless.org/docs/guides/unlisted-pages/
    */
   topic: z.string().optional(),
 });

package/overrides/Pagination.astro

@@ -1,19 +0,0 @@
----
-import Default from '@astrojs/starlight/components/Pagination.astro'
-import type { Props } from '@astrojs/starlight/props'
-
-import { isTopicFirstPage, isTopicLastPage } from '../lib/sidebar'
-
-const { id, pagination, sidebar } = Astro.props
-let { prev, next } = pagination
-
-if (isTopicFirstPage(sidebar, id)) {
-  prev = undefined
-}
-
-if (isTopicLastPage(sidebar, id)) {
-  next = undefined
-}
----
-
-<Default {...Astro.props} pagination={{ prev, next }}><slot /></Default>