@levino/shipyard-docs 0.6.2 → 0.6.3

package/src/routeHelpers.ts

@@ -1,4 +1,5 @@
 import type { CollectionEntry } from 'astro:content'
+import type { SingleVersionConfig, VersionConfig } from './index'
 
 /**
  * Configuration for generating static paths for a docs collection.
@@ -76,3 +77,223 @@ export const getDocPath = (
  * Type for docs collection entry with inferred data structure.
  */
 export type DocsEntry = CollectionEntry<'docs'>
+
+/**
+ * Get the URL path segment for a version.
+ * Uses the version's `path` property if defined, otherwise uses the version string.
+ *
+ * @param version - The version string to look up
+ * @param versions - The version configuration
+ * @returns The path segment to use in URLs, or undefined if version not found
+ */
+export const getVersionPath = (
+  version: string,
+  versions: VersionConfig,
+): string | undefined => {
+  const versionConfig = versions.available.find((v) => v.version === version)
+  if (!versionConfig) return undefined
+  return versionConfig.path ?? versionConfig.version
+}
+
+/**
+ * Get the current/default version from version configuration.
+ *
+ * @param versions - The version configuration
+ * @returns The current version string
+ */
+export const getCurrentVersion = (versions: VersionConfig): string => {
+  return versions.current
+}
+
+/**
+ * Get all available versions from version configuration.
+ *
+ * @param versions - The version configuration
+ * @returns Array of available version configurations
+ */
+export const getAvailableVersions = (
+  versions: VersionConfig,
+): SingleVersionConfig[] => {
+  return versions.available
+}
+
+/**
+ * Check if a version is deprecated.
+ *
+ * @param version - The version string to check
+ * @param versions - The version configuration
+ * @returns True if the version is in the deprecated list
+ */
+export const isVersionDeprecated = (
+  version: string,
+  versions: VersionConfig,
+): boolean => {
+  return versions.deprecated?.includes(version) ?? false
+}
+
+/**
+ * Get the stable version from configuration.
+ * Falls back to current if stable is not explicitly set.
+ *
+ * @param versions - The version configuration
+ * @returns The stable version string
+ */
+export const getStableVersion = (versions: VersionConfig): string => {
+  return versions.stable ?? versions.current
+}
+
+/**
+ * Find a version configuration by its version string or path.
+ *
+ * @param versionOrPath - The version string or path segment
+ * @param versions - The version configuration
+ * @returns The matching version config, or undefined if not found
+ */
+export const findVersionConfig = (
+  versionOrPath: string,
+  versions: VersionConfig,
+): SingleVersionConfig | undefined => {
+  return versions.available.find(
+    (v) => v.version === versionOrPath || v.path === versionOrPath,
+  )
+}
+
+/**
+ * Generate the full URL path for a versioned doc entry.
+ *
+ * URL structure with versions:
+ * - Without i18n: /[routeBasePath]/[version]/[...slug]
+ * - With i18n: /[locale]/[routeBasePath]/[version]/[...slug]
+ *
+ * @param id - The doc entry ID
+ * @param routeBasePath - The base path for routes
+ * @param hasI18n - Whether i18n is enabled
+ * @param version - The version path segment (not the version string, use getVersionPath first)
+ * @param currentLocale - The current locale (for i18n)
+ * @returns The full URL path including version
+ */
+export const getVersionedDocPath = (
+  id: string,
+  routeBasePath: string,
+  hasI18n: boolean,
+  version: string,
+  currentLocale?: string,
+): string => {
+  // Normalize base path - remove leading and trailing slashes
+  let normalizedBasePath = routeBasePath
+  while (normalizedBasePath.startsWith('/')) {
+    normalizedBasePath = normalizedBasePath.slice(1)
+  }
+  while (normalizedBasePath.endsWith('/')) {
+    normalizedBasePath = normalizedBasePath.slice(0, -1)
+  }
+
+  // Normalize version - remove leading and trailing slashes
+  let normalizedVersion = version
+  while (normalizedVersion.startsWith('/')) {
+    normalizedVersion = normalizedVersion.slice(1)
+  }
+  while (normalizedVersion.endsWith('/')) {
+    normalizedVersion = normalizedVersion.slice(0, -1)
+  }
+
+  if (hasI18n && currentLocale) {
+    // Remove locale prefix from id (e.g., 'en/guide/intro' -> 'guide/intro')
+    const pathWithoutLocale = id.includes('/')
+      ? id.slice(id.indexOf('/') + 1)
+      : id
+    return `/${currentLocale}/${normalizedBasePath}/${normalizedVersion}/${pathWithoutLocale}`
+  }
+
+  return `/${normalizedBasePath}/${normalizedVersion}/${id}`
+}
+
+/**
+ * Generate route parameters from a versioned doc entry's slug.
+ *
+ * @param slug - The slug from the doc entry (may include version prefix)
+ * @param hasI18n - Whether i18n is enabled
+ * @param version - The version path segment
+ * @returns Route parameters object including version
+ */
+export const getVersionedRouteParams = (
+  slug: string,
+  hasI18n: boolean,
+  version: string,
+) => {
+  const baseParams = getRouteParams(slug, hasI18n)
+  return {
+    ...baseParams,
+    version,
+  }
+}
+
+/**
+ * Convert a path from one version to another.
+ * Useful for "view this page in another version" links.
+ *
+ * @param currentPath - The current full URL path
+ * @param targetVersion - The target version path segment
+ * @param currentVersion - The current version path segment
+ * @returns The path with version replaced
+ */
+export const switchVersionInPath = (
+  currentPath: string,
+  targetVersion: string,
+  currentVersion: string,
+): string => {
+  // Replace the version segment in the path
+  // Handle both /docs/v1/page and /en/docs/v1/page patterns
+  return currentPath.replace(
+    new RegExp(`/${escapeRegex(currentVersion)}/`),
+    `/${targetVersion}/`,
+  )
+}
+
+/**
+ * Escape special regex characters in a string.
+ * @internal
+ */
+const escapeRegex = (str: string): string => {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
+/**
+ * Creates a Map for efficient version path lookups.
+ * Use this when processing many documents to avoid repeated array.find() calls.
+ *
+ * @param versions - The version configuration
+ * @returns A Map from version string to URL path segment
+ *
+ * @example
+ * ```ts
+ * const versionPathMap = createVersionPathMap(versionsConfig)
+ * // Now use versionPathMap.get(version) instead of getVersionPath(version, versionsConfig)
+ * for (const doc of docs) {
+ *   const version = getVersionFromDocId(doc.id)
+ *   const versionPath = versionPathMap.get(version) ?? version
+ * }
+ * ```
+ */
+export const createVersionPathMap = (
+  versions: VersionConfig,
+): Map<string, string> => {
+  const map = new Map<string, string>()
+  for (const v of versions.available) {
+    map.set(v.version, v.path ?? v.version)
+  }
+  return map
+}
+
+/**
+ * Creates a Set of deprecated versions for efficient lookup.
+ * Use this when checking many documents for deprecation status.
+ *
+ * @param versions - The version configuration
+ * @returns A Set of deprecated version strings
+ */
+export const createDeprecatedVersionSet = (
+  versions: VersionConfig,
+): Set<string> => {
+  return new Set(versions.deprecated ?? [])
+}

package/src/sidebarEntries.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it } from 'vitest'
 import type { DocsData } from './sidebarEntries'
-import { toSidebarEntries } from './sidebarEntries'
+import { filterDocsForVersion, toSidebarEntries } from './sidebarEntries'
 
 describe('toSidebarEntries', () => {
   it('should create a basic sidebar structure from flat docs', () => {
@@ -309,3 +309,156 @@ describe('toSidebarEntries', () => {
     expect(entries.page.collapsed).toBeUndefined()
   })
 })
+
+describe('filterDocsForVersion', () => {
+  it('should filter docs to only include entries for the specified version', () => {
+    const docs: DocsData[] = [
+      { id: 'v1/intro.md', title: 'Intro v1', path: '/docs/v1/intro' },
+      { id: 'v1/guide.md', title: 'Guide v1', path: '/docs/v1/guide' },
+      { id: 'v2/intro.md', title: 'Intro v2', path: '/docs/v2/intro' },
+      { id: 'v2/guide.md', title: 'Guide v2', path: '/docs/v2/guide' },
+      {
+        id: 'v2/new-feature.md',
+        title: 'New Feature',
+        path: '/docs/v2/new-feature',
+      },
+    ]
+
+    const v1Docs = filterDocsForVersion(docs, 'v1')
+    expect(v1Docs).toHaveLength(2)
+    expect(v1Docs.map((d) => d.title)).toEqual(['Intro v1', 'Guide v1'])
+
+    const v2Docs = filterDocsForVersion(docs, 'v2')
+    expect(v2Docs).toHaveLength(3)
+    expect(v2Docs.map((d) => d.title)).toEqual([
+      'Intro v2',
+      'Guide v2',
+      'New Feature',
+    ])
+  })
+
+  it('should strip version prefix from doc IDs', () => {
+    const docs: DocsData[] = [
+      {
+        id: 'v2/getting-started.md',
+        title: 'Getting Started',
+        path: '/docs/v2/getting-started',
+      },
+      {
+        id: 'v2/en/intro.md',
+        title: 'Introduction',
+        path: '/docs/v2/en/intro',
+      },
+    ]
+
+    const filtered = filterDocsForVersion(docs, 'v2')
+
+    expect(filtered[0].id).toBe('getting-started.md')
+    expect(filtered[1].id).toBe('en/intro.md')
+  })
+
+  it('should preserve other doc properties unchanged', () => {
+    const docs: DocsData[] = [
+      {
+        id: 'v1/page.md',
+        title: 'Page Title',
+        path: '/docs/v1/page',
+        sidebarPosition: 5,
+        sidebarLabel: 'Custom Label',
+        sidebarClassName: 'special-class',
+        pagination_next: 'next-page',
+        pagination_prev: 'prev-page',
+        link: true,
+      },
+    ]
+
+    const filtered = filterDocsForVersion(docs, 'v1')
+    expect(filtered[0]).toEqual({
+      id: 'page.md',
+      title: 'Page Title',
+      path: '/docs/v1/page',
+      sidebarPosition: 5,
+      sidebarLabel: 'Custom Label',
+      sidebarClassName: 'special-class',
+      pagination_next: 'next-page',
+      pagination_prev: 'prev-page',
+      link: true,
+    })
+  })
+
+  it('should return empty array when no docs match the version', () => {
+    const docs: DocsData[] = [
+      { id: 'v1/intro.md', title: 'Intro', path: '/docs/v1/intro' },
+    ]
+
+    const filtered = filterDocsForVersion(docs, 'v3')
+    expect(filtered).toEqual([])
+  })
+
+  it('should handle versioned docs with i18n locale prefixes', () => {
+    const docs: DocsData[] = [
+      {
+        id: 'v2/en/getting-started.md',
+        title: 'Getting Started (EN)',
+        path: '/en/docs/v2/getting-started',
+      },
+      {
+        id: 'v2/de/getting-started.md',
+        title: 'Erste Schritte (DE)',
+        path: '/de/docs/v2/getting-started',
+      },
+      {
+        id: 'v1/en/getting-started.md',
+        title: 'Getting Started v1',
+        path: '/en/docs/v1/getting-started',
+      },
+    ]
+
+    const filtered = filterDocsForVersion(docs, 'v2')
+    expect(filtered).toHaveLength(2)
+    // IDs should have version stripped but locale preserved
+    expect(filtered.map((d) => d.id)).toEqual([
+      'en/getting-started.md',
+      'de/getting-started.md',
+    ])
+  })
+
+  it('should work correctly with semantic version strings', () => {
+    const docs: DocsData[] = [
+      { id: 'v1.0/intro.md', title: 'Intro v1.0', path: '/docs/v1.0/intro' },
+      {
+        id: 'v2.0.0/intro.md',
+        title: 'Intro v2.0.0',
+        path: '/docs/v2.0.0/intro',
+      },
+    ]
+
+    const v1Docs = filterDocsForVersion(docs, 'v1.0')
+    expect(v1Docs).toHaveLength(1)
+    expect(v1Docs[0].title).toBe('Intro v1.0')
+
+    const v2Docs = filterDocsForVersion(docs, 'v2.0.0')
+    expect(v2Docs).toHaveLength(1)
+    expect(v2Docs[0].title).toBe('Intro v2.0.0')
+  })
+
+  it('should work with special version names like latest and next', () => {
+    const docs: DocsData[] = [
+      {
+        id: 'latest/intro.md',
+        title: 'Latest Intro',
+        path: '/docs/latest/intro',
+      },
+      { id: 'next/intro.md', title: 'Next Intro', path: '/docs/next/intro' },
+      { id: 'v1/intro.md', title: 'V1 Intro', path: '/docs/v1/intro' },
+    ]
+
+    const latestDocs = filterDocsForVersion(docs, 'latest')
+    expect(latestDocs).toHaveLength(1)
+    expect(latestDocs[0].title).toBe('Latest Intro')
+
+    const nextDocs = filterDocsForVersion(docs, 'next')
+    expect(nextDocs).toHaveLength(1)
+    expect(nextDocs[0].title).toBe('Next Intro')
+  })
+})

package/src/sidebarEntries.ts

@@ -1,4 +1,5 @@
 import type { Entry } from '@levino/shipyard-base'
+import { getVersionFromDocId, stripVersionFromDocId } from './versionHelpers'
 
 export interface DocsData {
   id: string
@@ -19,6 +20,38 @@ export interface DocsData {
   paginationPrev?: string | null
 }
 
+/**
+ * Filters docs data to only include entries for a specific version
+ * and strips the version prefix from doc IDs for proper sidebar tree building.
+ *
+ * @param docs - Array of DocsData entries
+ * @param version - The version to filter by
+ * @returns Filtered docs with version prefix stripped from IDs
+ *
+ * @example
+ * ```ts
+ * // Input: [{ id: 'v2/getting-started', path: '/docs/v2/getting-started', ... }]
+ * // Output: [{ id: 'getting-started', path: '/docs/v2/getting-started', ... }]
+ * const sidebarDocs = filterDocsForVersion(allDocs, 'v2')
+ * ```
+ */
+export const filterDocsForVersion = (
+  docs: readonly DocsData[],
+  version: string,
+): DocsData[] => {
+  return docs
+    .filter((doc) => {
+      const docVersion = getVersionFromDocId(doc.id)
+      return docVersion === version
+    })
+    .map((doc) => ({
+      ...doc,
+      // Strip version from ID so tree builds correctly
+      // e.g., "v2/en/getting-started" -> "en/getting-started"
+      id: stripVersionFromDocId(doc.id),
+    }))
+}
+
 interface TreeNode {
   readonly key: string
   readonly label: string

package/src/versionHelpers.ts

@@ -0,0 +1,64 @@
+/**
+ * Helper functions for parsing and manipulating version strings in doc IDs.
+ * These are low-level utilities used by other modules.
+ */
+
+/**
+ * Checks if a string looks like a version identifier.
+ * Matches: v1.0, v2.0.0, latest, next, main, etc.
+ */
+export const isVersionLikeString = (str: string): boolean => {
+  // Match common version patterns
+  return /^(v?\d+(\.\d+)*|latest|next|main|master|canary|beta|alpha|rc\d*|stable)$/i.test(
+    str,
+  )
+}
+
+/**
+ * Extracts the version from a versioned document ID.
+ * The version is expected to be the first path segment.
+ *
+ * @param docId - The document ID (e.g., "v1.0/en/getting-started")
+ * @returns The version string or undefined if not found
+ *
+ * @example
+ * ```ts
+ * getVersionFromDocId("v1.0/en/getting-started") // "v1.0"
+ * getVersionFromDocId("latest/en/index") // "latest"
+ * getVersionFromDocId("en/getting-started") // undefined (non-versioned)
+ * ```
+ */
+export const getVersionFromDocId = (docId: string): string | undefined => {
+  const parts = docId.split('/')
+  // For versioned docs, first part is the version
+  // We check if it looks like a version (starts with 'v' and has numbers, or is 'latest', 'next', etc.)
+  if (parts.length > 0) {
+    const potentialVersion = parts[0]
+    if (isVersionLikeString(potentialVersion)) {
+      return potentialVersion
+    }
+  }
+  return undefined
+}
+
+/**
+ * Strips the version prefix from a versioned document ID.
+ * Returns the ID without the version for use in routing.
+ *
+ * @param docId - The document ID (e.g., "v1.0/en/getting-started")
+ * @returns The ID without version prefix (e.g., "en/getting-started")
+ *
+ * @example
+ * ```ts
+ * stripVersionFromDocId("v1.0/en/getting-started") // "en/getting-started"
+ * stripVersionFromDocId("latest/en/index") // "en/index"
+ * stripVersionFromDocId("en/getting-started") // "en/getting-started" (unchanged)
+ * ```
+ */
+export const stripVersionFromDocId = (docId: string): string => {
+  const version = getVersionFromDocId(docId)
+  if (version) {
+    return docId.slice(version.length + 1) // +1 for the slash
+  }
+  return docId
+}