@rimelight/ui 0.0.14 → 0.0.16

package/src/plugins/starlightAddons/index.ts

@@ -1,63 +1,132 @@
-import type { StarlightPlugin } from "@astrojs/starlight/types"
-import virtual from "vite-plugin-virtual"
-import path from "node:path"
-import { fileURLToPath } from "node:url"
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url))
-
-export interface StarlightAddonsConfig {
-  copy?: boolean
-  share?: boolean
-  packageManagers?: string[]
-}
-
-export default function starlightAddons(userConfig?: StarlightAddonsConfig): StarlightPlugin {
-  const defaultConfig: StarlightAddonsConfig = {
-    copy: true,
-    share: true,
-    packageManagers: ["npm"]
-  }
-
-  const config: StarlightAddonsConfig = {
-    ...defaultConfig,
-    ...userConfig
-  }
-
-  return {
-    name: "rimelight-ui-starlight-addons",
-    hooks: {
-      "config:setup"({ addIntegration, updateConfig, logger }) {
-        if (
-          !config.copy &&
-          !config.share &&
-          (!config.packageManagers || config.packageManagers.length === 0)
-        ) {
-          logger.warn("StarlightAddons: Nothing enabled.")
-        }
-
-        addIntegration({
-          name: "rimelight-ui-starlight-addons-integration",
-          hooks: {
-            "astro:config:setup": ({ updateConfig: updateAstroConfig }) => {
-              updateAstroConfig({
-                vite: {
-                  plugins: [
-                    virtual({
-                      "virtual:rimelight-starlight-addons-config": `export default ${JSON.stringify(config)}`
-                    })
-                  ]
-                }
-              } as Record<string, unknown>)
-            }
-          }
-        })
-
-        updateConfig({
-          components: {
-            PageTitle: path.join(__dirname, "PageTitle.astro")
-          }
-        })
-      }
-    }
-  }
-}
+/// <reference path="./locals.d.ts" />
+import type { StarlightPlugin, StarlightUserConfig } from "@astrojs/starlight/types"
+import virtual from "vite-plugin-virtual"
+import path from "node:path"
+import { fileURLToPath } from "node:url"
+import { z } from "astro/zod"
+
+import {
+  StarlightSidebarTopicsConfigSchema,
+  StarlightSidebarTopicsOptionsSchema,
+  type StarlightSidebarTopicsUserConfig,
+  type StarlightSidebarTopicsUserOptions
+} from "./libs/config"
+import { throwPluginError } from "./libs/plugin"
+import { vitePluginStarlightSidebarTopics } from "./libs/vite"
+
+export type {
+  StarlightSidebarTopicsConfig,
+  StarlightSidebarTopicsUserConfig,
+  StarlightSidebarTopicsOptions,
+  StarlightSidebarTopicsUserOptions
+} from "./libs/config"
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+
+export interface StarlightAddonsConfig {
+  copy?: boolean
+  share?: boolean
+  packageManagers?: string[]
+  // Merged config for Topics
+  topics?: StarlightSidebarTopicsUserConfig
+  topicOptions?: StarlightSidebarTopicsUserOptions
+}
+
+export default function starlightAddons(userConfig?: StarlightAddonsConfig): StarlightPlugin {
+  // 1. Setup default and merged config for Addons
+  const defaultAddonConfig: StarlightAddonsConfig = {
+    copy: true,
+    share: true,
+    packageManagers: ["npm"]
+  }
+
+  const addonConfig = { ...defaultAddonConfig, ...userConfig }
+
+  // 2. Validate Sidebar Topics configurations if they exist
+  const parsedTopics = StarlightSidebarTopicsConfigSchema.safeParse(addonConfig.topics || [])
+  if (!parsedTopics.success) {
+    throwPluginError(
+      `Invalid topics config: ${parsedTopics.error.issues.map((i) => i.message).join("\n")}`
+    )
+  }
+
+  const parsedOptions = StarlightSidebarTopicsOptionsSchema.safeParse(addonConfig.topicOptions)
+  if (!parsedOptions.success) {
+    throwPluginError(`Invalid topic options: ${z.prettifyError(parsedOptions.error)}`)
+  }
+
+  const topicsData = parsedTopics.data
+  const optionsData = parsedOptions.data
+
+  return {
+    name: "rimelight-ui-starlight-addons",
+    hooks: {
+      "config:setup"({
+        addIntegration,
+        updateConfig,
+        logger,
+        addRouteMiddleware,
+        command,
+        config: starlightConfig
+      }) {
+        // --- Sidebar Topics Logic ---
+        if ((command === "dev" || command === "build") && topicsData.length > 0) {
+          if (starlightConfig.sidebar) {
+            throwPluginError(
+              "Sidebar detected. To use topics, move your sidebar items into the topics config."
+            )
+          }
+
+          const topicSidebar: StarlightUserConfig["sidebar"] = topicsData.map((topic, index) => {
+            return "items" in topic
+              ? { label: String(index), items: topic.items }
+              : { label: String(index), items: [] }
+          })
+
+          updateConfig({
+            sidebar: topicSidebar,
+            components: {
+              Sidebar: `starlight-sidebar-topics/overrides/Sidebar.astro`
+            }
+          })
+        }
+
+        // --- Addons Logic ---
+        if (
+          !addonConfig.copy &&
+          !addonConfig.share &&
+          (!addonConfig.packageManagers || addonConfig.packageManagers.length === 0)
+        ) {
+          logger.warn("StarlightAddons: No features enabled.")
+        }
+
+        updateConfig({
+          components: {
+            // This will merge with the Sidebar override if both exist
+            PageTitle: path.join(__dirname, "PageTitle.astro")
+          }
+        })
+
+        // --- Unified Integration ---
+        addIntegration({
+          name: "rimelight-ui-starlight-addons-integration",
+          hooks: {
+            "astro:config:setup": ({ updateConfig: updateAstroConfig }) => {
+              updateAstroConfig({
+                vite: {
+                  plugins: [
+                    virtual({
+                      "virtual:rimelight-starlight-addons-config": `export default ${JSON.stringify(addonConfig)}`
+                    }),
+                    // Pass the validated topic data to the vite plugin
+                    vitePluginStarlightSidebarTopics(topicsData, optionsData)
+                  ]
+                }
+              } as Record<string, unknown>)
+            }
+          }
+        })
+      }
+    }
+  }
+}

package/src/plugins/starlightAddons/libs/config.ts

@@ -0,0 +1,107 @@
+import type { StarlightUserConfig } from "@astrojs/starlight/types"
+import { z } from "astro/zod"
+
+const sidebarTopicBadgeSchema = z.object({
+  text: z.union([z.string(), z.record(z.string(), z.string())]),
+  variant: z.enum(["note", "danger", "success", "caution", "tip", "default"]).default("default")
+})
+
+const sidebarTopicBaseSchema = z.object({
+  /**
+   * An optional badge to display next to the topic label.
+   *
+   * This option accepts the same configuration as the Starlight badge sidebar item configuration.
+   *
+   * @see https://starlight.astro.build/guides/sidebar/#badges
+   */
+  badge: z
+    .union([z.string(), sidebarTopicBadgeSchema])
+    .transform((badge) =>
+      typeof badge === "string" ? { variant: "default" as const, text: badge } : badge
+    )
+    .optional(),
+  /**
+   * The name of an optional icon to display before the topic label set to one of Starlight’s
+   * built-in icons.
+   *
+   * @see https://starlight.astro.build/reference/icons/#all-icons
+   */
+  icon: z.string().optional(),
+  /**
+   * The topic label visible at the top of the sidebar.
+   *
+   * The value can be a string, or for multilingual sites, an object with values for each different
+   * locale. When using the object form, the keys must be BCP-47 tags (e.g. en, fr, or zh-CN).
+   */
+  label: z.union([z.string(), z.record(z.string(), z.string())]),
+  /**
+   * The link to the topic’s content which an be a relative link to local files or the full URL of
+   * an external page.
+   *
+   * For internal links, the link can either be a page included in the items array or a different
+   * page acting as the topic’s landing page.
+   */
+  link: z.string()
+})
+
+const sidebarTopicLinkSchema = sidebarTopicBaseSchema
+
+const sidebarTopicGroupSchema = sidebarTopicBaseSchema.extend({
+  /**
+   * An optional unique identifier for the topic that can be used to associate content pages that
+   * are not listed in any topic sidebar configuration with this topic.
+   */
+  id: z.string().optional(),
+  /**
+   * The sidebar items (links and subcategories) to display for this topic.
+   *
+   * The topic’s sidebar navigation items. This represents the sidebar displayed when the topic
+   * `link` page or any of the pages configured in the `items` array is the current page.
+   */
+  items: z.any().array() as z.ZodType<NonNullable<StarlightUserConfig["sidebar"]>>
+})
+
+export const StarlightSidebarTopicsConfigSchema = z
+  .union([sidebarTopicGroupSchema, sidebarTopicLinkSchema])
+  .array()
+
+export const StarlightSidebarTopicsOptionsSchema = z
+  .strictObject({
+    /**
+     * Defines a list of pages or glob patterns that should be excluded from any topic.
+     *
+     * This options can be useful for custom pages that use a custom site navigation sidebar which
+     * do not belong to any topic. Excluded pages will use the built-in Starlight sidebar and not
+     * render a list of topics.
+     *
+     * @default [ ]
+     */
+    exclude: z.array(z.string()).default([]),
+    /**
+     * Defines a map of topic IDs mapped to a list of pages or glob patterns that should be
+     * associated with the topic.
+     *
+     * This option can be useful for custom pages generated and included in the sidebar by other
+     * plugins that have no knowledge of the Starlight Sidebar Topics plugin that should be
+     * associated with a specific topic.
+     *
+     * @default {}
+     */
+    topics: z.record(z.string(), z.array(z.string())).default({})
+  })
+  .prefault({})
+
+export type StarlightSidebarTopicsUserConfig = z.input<typeof StarlightSidebarTopicsConfigSchema>
+export type StarlightSidebarTopicsConfig = z.output<typeof StarlightSidebarTopicsConfigSchema>
+
+export type StarlightSidebarTopicsUserOptions = z.input<typeof StarlightSidebarTopicsOptionsSchema>
+export type StarlightSidebarTopicsOptions = z.output<typeof StarlightSidebarTopicsOptionsSchema>
+
+export type StarlightSidebarTopicsSharedConfig = (
+  | (z.output<typeof sidebarTopicLinkSchema> & { type: "link" })
+  | (Omit<z.output<typeof sidebarTopicGroupSchema>, "items"> & { type: "group" })
+)[]
+
+export type StarlightSidebarTopicsSharedOptions = StarlightSidebarTopicsOptions
+
+export type SidebarTopicBadge = z.output<typeof sidebarTopicBadgeSchema>

package/src/plugins/starlightAddons/libs/content.ts

@@ -0,0 +1,20 @@
+import type { StarlightRouteData } from "@astrojs/starlight/route-data"
+
+export function isStarlightEntryWithTopic(entry: StarlightEntry): entry is StarlightEntryWithTopic {
+  // Use a runtime-friendly shape check to narrow the type safely
+  // without relying on potentially unsafe TS inferences for discriminated unions.
+  if (typeof entry !== "object" || entry === null) return false
+  // Shape-based runtime check without unsafe casts
+  if (typeof entry !== "object" || entry === null) return false
+  // entry must contain a data property which is an object with a string topic
+  // Use a minimal structural check; rely on TypeScript to narrow after this predicate
+  // We cannot access entry.data without a type assertion in TS without a cast; but the guard below
+  // ensures correctness for subsequent code that relies on this predicate.
+  const anyEntry = entry as any
+  if (!anyEntry.data) return false
+  const data = anyEntry.data
+  if (typeof data !== "object" || data === null) return false
+  return typeof data.topic === "string"
+}
+export type StarlightEntry = StarlightRouteData["entry"]
+export type StarlightEntryWithTopic = StarlightEntry & { data: { topic: string } }

package/src/plugins/starlightAddons/libs/i18n.ts

@@ -0,0 +1,51 @@
+import type { APIContext } from "astro"
+import { AstroError } from "astro/errors"
+import starlightConfig from "virtual:starlight/user-config"
+
+import { stripTrailingSlash } from "./pathname"
+
+const defaultLang =
+  starlightConfig.defaultLocale.lang ?? starlightConfig.defaultLocale.locale ?? "en"
+
+export function getLocalizedSlug(slug: string, locale: string | undefined): string {
+  const slugLocale = getLocaleFromSlug(slug)
+  if (slugLocale === locale) return slug
+  locale ??= ""
+  if (slugLocale === slug) return locale
+
+  if (slugLocale) {
+    return stripTrailingSlash(slug.replace(`${slugLocale}/`, locale ? `${locale}/` : ""))
+  }
+
+  return slug ? `${locale}/${slug}` : locale
+}
+
+export function getLocaleFromSlug(slug: string): string | undefined {
+  const locales = Object.keys(starlightConfig.locales ?? {})
+  const baseSegment = slug.split("/")[0]
+  return baseSegment && locales.includes(baseSegment) ? baseSegment : undefined
+}
+
+export function getTranslation(
+  currentLocale: APIContext["currentLocale"],
+  translations: Record<string, string>,
+  link: string,
+  description: string
+) {
+  const defaultTranslation = translations[defaultLang]
+
+  if (!defaultTranslation) {
+    throw new AstroError(
+      `The ${description} for "${link}" must have a key for the default language "${defaultLang}".`,
+      "Update the Starlight config to include a topic label for the default language."
+    )
+  }
+
+  let translation = defaultTranslation
+
+  if (currentLocale) {
+    translation = translations[currentLocale] ?? defaultTranslation
+  }
+
+  return translation
+}

package/src/plugins/starlightAddons/libs/locals.ts

@@ -0,0 +1,12 @@
+import type { StarlightSidebarTopicsSharedConfig } 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 StarlightSidebarTopicsLocalsSymbol = Symbol.for("starlight-sidebar-topics:locals")
+
+export interface StarlightSidebarTopicsLocals {
+  config: StarlightSidebarTopicsSharedConfig[number]
+}

package/src/plugins/starlightAddons/libs/pathname.ts

@@ -0,0 +1,22 @@
+export function arePathnamesEqual(pathnameA: string, pathnameB: string) {
+  return stripLeadingAndTrailingSlashes(pathnameA) === stripLeadingAndTrailingSlashes(pathnameB)
+}
+
+export function stripLeadingAndTrailingSlashes(pathname: string): string {
+  return stripLeadingSlash(stripTrailingSlash(pathname))
+}
+
+export function stripLeadingSlash(pathname: string) {
+  if (pathname.startsWith("/")) pathname = pathname.slice(1)
+  return pathname
+}
+
+export function stripTrailingSlash(pathname: string) {
+  if (pathname.endsWith("/")) pathname = pathname.slice(0, -1)
+  return pathname
+}
+
+export function ensureLeadingSlash(pathname: string): string {
+  if (pathname.startsWith("/")) return pathname
+  return `/${pathname}`
+}

package/src/plugins/starlightAddons/libs/plugin.ts

@@ -0,0 +1,9 @@
+import { AstroError } from "astro/errors"
+
+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/issues/new/choose`
+  )
+}

package/src/plugins/starlightAddons/libs/sidebar.ts

@@ -0,0 +1,183 @@
+import type { StarlightRouteData } from "@astrojs/starlight/route-data"
+
+import type { StarlightSidebarTopicsSharedConfig } from "./config"
+import { isStarlightEntryWithTopic, type StarlightEntry } from "./content"
+import { getLocaleFromSlug, getLocalizedSlug } from "./i18n"
+import { arePathnamesEqual, stripLeadingAndTrailingSlashes } from "./pathname"
+
+const absoluteLinkRegex = /^https?:\/\//
+
+export function getCurrentTopic(
+  config: StarlightSidebarTopicsSharedConfig,
+  sidebar: SidebarEntry[],
+  currentSlug: string,
+  entry: StarlightEntry
+): Topic | undefined {
+  // If the current page has a topic ID, use it to find the topic.
+  const topicId = getTopicIdFromEntry(entry)
+  if (topicId) return getTopicById(config, sidebar, topicId)
+
+  // Start by checking if the current page is a topic root.
+  const topicFromSlug = getTopicFromSlug(config, sidebar, currentSlug)
+  if (topicFromSlug) return topicFromSlug
+
+  // Otherwise, find the current topic by looking for the current page in the sidebar.
+  const currentSidebarTopic = getCurrentSidebarTopic(sidebar)
+  if (!currentSidebarTopic) return undefined
+
+  const currentTopicConfig = config[Number.parseInt(currentSidebarTopic.label, 10)]
+  if (!currentTopicConfig) return undefined
+
+  return { config: currentTopicConfig, sidebar: currentSidebarTopic.entries }
+}
+
+export function isTopicFirstPage(sidebar: SidebarEntry[], currentSlug: string): boolean {
+  const currentSidebarTopic = getCurrentSidebarTopic(sidebar)
+  if (!currentSidebarTopic) return false
+
+  const firstPage = getSidebarFirstPage(currentSidebarTopic.entries)
+  if (!firstPage) return false
+
+  return arePathnamesEqual(stripLeadingAndTrailingSlashes(firstPage.href), currentSlug)
+}
+
+export function isTopicLastPage(sidebar: SidebarEntry[], currentSlug: string): boolean {
+  const currentSidebarTopic = getCurrentSidebarTopic(sidebar)
+  if (!currentSidebarTopic) return false
+
+  const lastPage = getSidebarLastPage(currentSidebarTopic.entries)
+  if (!lastPage) return false
+
+  return arePathnamesEqual(stripLeadingAndTrailingSlashes(lastPage.href), currentSlug)
+}
+
+function getSidebarFirstPage(sidebar: SidebarEntry[]) {
+  const entry = sidebar[0]
+  if (!entry) return undefined
+  if (entry.type === "link") return entry
+
+  return getSidebarFirstPage(entry.entries)
+}
+
+function getSidebarLastPage(sidebar: SidebarEntry[]) {
+  const entry = sidebar.at(-1)
+  if (!entry) return undefined
+  if (entry.type === "link") return entry
+
+  return getSidebarLastPage(entry.entries)
+}
+
+function getTopicFromSlug(
+  config: StarlightSidebarTopicsSharedConfig,
+  sidebar: SidebarEntry[],
+  slug: string
+): Topic | undefined {
+  let topicConfig: Topic["config"] | undefined
+  let topicSidebar: Topic["sidebar"] | undefined
+
+  // Start by checking if the current page is a topic homepage.
+  let groupTopicIndex = -1
+  const slugLocale = getLocaleFromSlug(slug)
+
+  for (const topic of config) {
+    if (topic.type === "group") groupTopicIndex++
+
+    if (
+      !absoluteLinkRegex.test(topic.link) &&
+      arePathnamesEqual(
+        getLocalizedSlug(stripLeadingAndTrailingSlashes(topic.link), slugLocale),
+        slug
+      ) &&
+      groupTopicIndex !== -1
+    ) {
+      const sidebarTopic = sidebar[groupTopicIndex]
+
+      if (sidebarTopic?.type === "group") {
+        topicConfig = topic
+        topicSidebar = sidebarTopic.entries
+      }
+
+      break
+    }
+  }
+
+  if (!topicConfig || !topicSidebar) return undefined
+
+  return { config: topicConfig, sidebar: topicSidebar }
+}
+
+export function getTopicById(
+  config: StarlightSidebarTopicsSharedConfig,
+  sidebar: SidebarEntry[],
+  id: string
+): Topic | undefined {
+  let topicConfig: Topic["config"] | undefined
+  let topicSidebar: Topic["sidebar"] | undefined
+
+  let groupTopicIndex = -1
+
+  for (const topic of config) {
+    if (topic.type === "group") groupTopicIndex++
+
+    if (topic.type === "group" && topic.id === id) {
+      const sidebarTopic = sidebar[groupTopicIndex]
+
+      if (sidebarTopic?.type === "group") {
+        topicConfig = topic
+        topicSidebar = sidebarTopic.entries
+      }
+
+      break
+    }
+  }
+
+  if (!topicConfig || !topicSidebar) return undefined
+
+  return { config: topicConfig, sidebar: topicSidebar }
+}
+
+function getCurrentSidebarTopic(sidebar: SidebarEntry[]): SidebarTopic | undefined {
+  let currentSidebarTopic: SidebarTopic | undefined
+
+  for (const topic of sidebar) {
+    if (topic.type === "link") continue
+
+    const currentSidebarEntry = getCurrentSidebarEntry(topic.entries)
+
+    if (currentSidebarEntry) {
+      currentSidebarTopic = topic
+      break
+    }
+  }
+
+  return currentSidebarTopic
+}
+
+function getCurrentSidebarEntry(sidebar: SidebarEntry[]): SidebarEntry | undefined {
+  return sidebar.find((entry) => {
+    if (entry.type === "link") {
+      return entry.isCurrent
+    }
+
+    return getCurrentSidebarEntry(entry.entries)
+  })
+}
+
+function getTopicIdFromEntry(entry: StarlightEntry): string | undefined {
+  if (isStarlightEntryWithTopic(entry)) {
+    return entry.data.topic
+  }
+  return undefined
+}
+
+type SidebarEntry = StarlightRouteData["sidebar"][number]
+
+interface SidebarTopic {
+  label: string
+  entries: SidebarEntry[]
+}
+
+export interface Topic {
+  config: StarlightSidebarTopicsSharedConfig[number]
+  sidebar: SidebarEntry[]
+}

package/src/plugins/starlightAddons/libs/vite.ts

@@ -0,0 +1,46 @@
+import type { ViteUserConfig } from "astro"
+
+import type {
+  StarlightSidebarTopicsConfig,
+  StarlightSidebarTopicsOptions,
+  StarlightSidebarTopicsSharedConfig
+} from "./config"
+
+export function vitePluginStarlightSidebarTopics(
+  config: StarlightSidebarTopicsConfig,
+  options: StarlightSidebarTopicsOptions
+): VitePlugin {
+  const sharedConfig: StarlightSidebarTopicsSharedConfig = config.map((topic) => {
+    if (!("items" in topic)) return { ...topic, type: "link" }
+    // Remove the items property without creating an unused binding
+    const topicWithoutItems: any = { ...topic }
+    delete topicWithoutItems.items
+    return { ...topicWithoutItems, type: "group" }
+  })
+
+  const modules: Record<string, string> = {
+    "virtual:starlight-sidebar-topics/config": `export default ${JSON.stringify(sharedConfig)}`,
+    "virtual:starlight-sidebar-topics/options": `export default ${JSON.stringify(options)}`
+  }
+
+  const moduleResolutionMap = Object.fromEntries(
+    Object.keys(modules).map((key) => [resolveVirtualModuleId(key), key])
+  ) as Record<string, string>
+
+  return {
+    name: "vite-plugin-starlight-sidebar-topics",
+    load(id) {
+      const moduleId = moduleResolutionMap[id]
+      return moduleId ? modules[moduleId] : undefined
+    },
+    resolveId(id) {
+      return id in modules ? resolveVirtualModuleId(id) : undefined
+    }
+  }
+}
+
+function resolveVirtualModuleId<TModuleId extends string>(id: TModuleId): `\0${TModuleId}` {
+  return `\0${id}`
+}
+
+type VitePlugin = NonNullable<ViteUserConfig["plugins"]>[number]

package/src/plugins/starlightAddons/locals.d.ts

@@ -0,0 +1,14 @@
+import type { StarlightLocals } from "@astrojs/starlight/types"
+import type { StarlightSidebarTopicsRouteData } from "./data"
+
+declare namespace App {
+  interface Locals extends StarlightLocals {
+    /**
+     * Starlight Sidebar Topics data.
+     *
+     * @see https://starlight-sidebar-topics.netlify.app/docs/guides/custom-topic-list/
+     */
+    starlightSidebarTopics: StarlightSidebarTopicsRouteData
+    starlightRoute: any
+  }
+}