polen 0.11.0-next.1 → 0.11.0-next.11

package/src/api/schema/schema.ts

@@ -1,10 +1,13 @@
 import type { GraphqlChangeset } from '#lib/graphql-changeset/index'
 
-export * as DataSources from './data-sources/data-sources.js'
-
-export * from './read.js'
+// Re-export everything from isomorphic layer
+export * from '../iso/schema/constants.js'
+export * as Routing from '../iso/schema/routing.js'
 
+// Server-only exports
+export * as DataSources from './data-sources/data-sources.js'
 export * from './metadata.js'
+export * from './read.js'
 
 export type ChangeSets = GraphqlChangeset.ChangeSet[]
 
@@ -17,53 +20,3 @@ export interface ChangelogData {
   changes: GraphqlChangeset.ChangeSet['changes']
   date: string
 }
-
-/**
- * Constants for schema versioning
- */
-
-/**
- * The version identifier for the latest schema
- */
-export const VERSION_LATEST = `latest`
-
-/**
- * Fallback version name when date parsing fails
- */
-export const VERSION_UNKNOWN_FALLBACK = `unknown`
-
-/**
- * Convert a date to a version string in YYYY-MM-DD format
- */
-export const dateToVersionString = (date: Date): string => {
-  return date.toLocaleDateString('en-CA')
-}
-
-/**
- * Determine if a version at the given index should have a changelog file.
- * Only non-oldest versions get changelog files.
- */
-export const shouldVersionHaveChangelog = (versionIndex: number, totalVersions: number): boolean => {
-  return versionIndex < totalVersions - 1
-}
-
-/**
- * Convert a version string back to a Date
- */
-export const versionStringToDate = (version: string): Date => {
-  if (version === VERSION_LATEST) {
-    return new Date()
-  }
-
-  // Use modern date parsing - the version string should be in YYYY-MM-DD format
-  // which is ISO 8601 compatible
-  const parsedDate = new Date(version + 'T00:00:00Z')
-
-  // Check if the date is valid
-  if (!isNaN(parsedDate.getTime())) {
-    return parsedDate
-  }
-
-  // Throw error for invalid dates instead of silently defaulting
-  throw new Error(`Invalid version string: ${version}`)
-}

package/src/api/schema-source/schema-source.ts

@@ -157,13 +157,13 @@ export const createSchemaSource = (config: SchemaSourceConfig) => {
     },
 
     writeAllAssets: async (
-      schemaData: Awaited<ReturnType<typeof Schema.readOrThrow>>,
+      schemaData: Awaited<ReturnType<typeof Schema.readOrThrow>>['data'],
       metadata: Schema.SchemaMetadata,
     ) => {
       if (!schemaData) return
 
       // Write schema and changelog files
-      for (const [index, version] of schemaData.entries()) {
+      for (const [index, version] of schemaData!.entries()) {
         const versionName = index === 0 ? Schema.VERSION_LATEST : Schema.dateToVersionString(version.date)
 
         // Write schema file
@@ -173,7 +173,7 @@ export const createSchemaSource = (config: SchemaSourceConfig) => {
         )
 
         // Write changelog file (except for the oldest/last version)
-        if (Schema.shouldVersionHaveChangelog(index, schemaData.length)) {
+        if (Schema.shouldVersionHaveChangelog(index, schemaData!.length)) {
           const changelogData = {
             changes: version.changes,
             date: version.date.toISOString(),

package/src/api/static/manifest.ts

@@ -5,7 +5,7 @@ export const PolenBuildManifestSchema = z.object({
   type: z.enum([`ssg`, `ssr`]),
   version: z.string(),
   basePath: z.string(),
-}).loose()
+})
 
 export type PolenBuildManifest = z.infer<typeof PolenBuildManifestSchema>
 

package/src/api/vite/plugins/build.ts

@@ -75,6 +75,9 @@ export const Build = (config: Config.Config): Vite.Plugin[] => {
           // @see https://github.com/vitejs/vite/issues/20098
           ssr: {
             noExternal: true,
+            // Exclude lightningcss from bundling due to native bindings
+            // @see https://github.com/parcel-bundler/lightningcss/issues/701
+            external: ['lightningcss'],
           },
           environments: {
             ssr: {

package/src/api/vite/plugins/core.ts

@@ -1,22 +1,18 @@
 import type { Config } from '#api/config/index'
 import { Content } from '#api/content/$'
 import { createNavbar } from '#api/content/navbar'
+import { Api } from '#api/index'
 import { VitePluginSelfContainedMode } from '#cli/_/self-contained-mode'
-import { Hono } from '#dep/hono/index'
 import type { ReactRouter } from '#dep/react-router/index'
 import type { Vite } from '#dep/vite/index'
 import { VitePluginJson } from '#lib/vite-plugin-json/index'
 import { ViteVirtual } from '#lib/vite-virtual/index'
 import { debugPolen } from '#singletons/debug'
 import { superjson } from '#singletons/superjson'
-import * as HonoNodeServer from '@hono/node-server'
-import { serveStatic } from '@hono/node-server/serve-static'
 import { Json, Str } from '@wollybeard/kit'
-import * as NodePath from 'node:path'
 import type { ProjectData } from '../../../project-data.js'
 import { SchemaAugmentation } from '../../schema-augmentation/index.js'
 import { Schema } from '../../schema/index.js'
-import { createLogger } from '../logger.js'
 import { polenVirtual } from '../vi.js'
 import { Pages } from './pages.js'
 import { SchemaAssets } from './schema-assets.js'
@@ -35,15 +31,15 @@ export const Core = (config: Config.Config): Vite.PluginOption[] => {
 
   const readSchema = async () => {
     if (schemaCache === null) {
-      const schema = await Schema.readOrThrow({
+      const schemaResult = await Schema.readOrThrow({
         ...config.schema,
         projectRoot: config.paths.project.rootDir,
       })
       // todo: augmentations scoped to a version
-      schema?.forEach(version => {
+      schemaResult.data?.forEach(version => {
         SchemaAugmentation.apply(version.after, config.schemaAugmentations)
       })
-      schemaCache = schema
+      schemaCache = schemaResult
     }
     return schemaCache
   }
@@ -166,8 +162,8 @@ export const Core = (config: Config.Config): Vite.PluginOption[] => {
             const debug = debugPolen.sub(`module-project-schema`)
             debug(`load`, { id: viProjectSchema.id })
 
-            const schema = await readSchema()
-            return superjson.stringify(schema)
+            const schemaResult = await readSchema()
+            return superjson.stringify(schemaResult.data)
           },
         },
         {
@@ -191,18 +187,19 @@ export const Core = (config: Config.Config): Vite.PluginOption[] => {
 
             debug(`load`, { id: viProjectData.id })
 
-            const schema = await readSchema()
+            const schemaResult = await readSchema()
 
             const navbar = []
 
             // ━ Schema presence causes adding some navbar items
-            if (schema) {
+            if (schemaResult.data) {
               // IMPORTANT: Always ensure paths start with '/' for React Router compatibility.
               // Without the leading slash, React Router treats paths as relative, which causes
               // hydration mismatches between SSR (where base path is prepended) and client
               // (where basename is configured). This ensures consistent behavior.
-              navbar.push({ pathExp: `/reference`, title: `Reference` })
-              if (schema.length > 1) {
+              const referencePath = Api.Schema.Routing.createReferenceBasePath()
+              navbar.push({ pathExp: referencePath, title: `Reference` })
+              if (schemaResult.data.length > 1) {
                 navbar.push({ pathExp: `/changelog`, title: `Changelog` })
               }
             }

package/src/api/vite/plugins/main.ts

@@ -2,9 +2,8 @@ import type { Config } from '#api/config/index'
 import type { Vite } from '#dep/vite/index'
 import { vitePluginSsrCss } from '@hiogawa/vite-plugin-ssr-css'
 import ViteReact from '@vitejs/plugin-react-oxc'
-import { Arr, Path } from '@wollybeard/kit'
+import { Path } from '@wollybeard/kit'
 import Inspect from 'vite-plugin-inspect'
-import Restart from 'vite-plugin-restart'
 import { Branding } from './branding.js'
 import { Build } from './build.js'
 import { Core } from './core.js'
@@ -26,13 +25,6 @@ export const Main = (
     plugins.push(plugin)
   }
 
-  if (Arr.isntEmpty(config.watch.also)) {
-    const plugin = Restart({
-      restart: config.watch.also,
-    })
-    plugins.push(plugin)
-  }
-
   plugins.push(
     ViteReact(),
     vitePluginSsrCss({

package/src/api/vite/plugins/schema-assets.ts

@@ -9,6 +9,7 @@ import { debugPolen } from '#singletons/debug'
 import { Cache } from '@wollybeard/kit'
 import * as NodeFs from 'node:fs/promises'
 import * as NodePath from 'node:path'
+import type { NonEmptyChangeSets } from '../../schema/schema.js'
 import { polenVirtual } from '../vi.js'
 
 export const viProjectSchemaMetadata = polenVirtual([`project`, `schema-metadata`])
@@ -35,27 +36,28 @@ export const SchemaAssets = (config: Config.Config): Vite.Plugin => {
 
   // Helper to load and process schema data
   const loadAndProcessSchemaData = Cache.memoize(async () => {
-    const schemaData = await Schema.readOrThrow({
+    const schemaResult = await Schema.readOrThrow({
       ...config.schema,
       projectRoot: config.paths.project.rootDir,
     })
 
-    if (!schemaData) {
+    if (!schemaResult.data) {
       const metadata: Schema.SchemaMetadata = { hasSchema: false, versions: [] }
       return {
         schemaData: null,
         metadata,
+        source: schemaResult.source,
       }
     }
 
     // Apply augmentations
-    schemaData.forEach(version => {
+    schemaResult.data.forEach(version => {
       SchemaAugmentation.apply(version.after, config.schemaAugmentations)
     })
 
     // Build metadata
     const versionStrings: string[] = []
-    for (const [index, version] of schemaData.entries()) {
+    for (const [index, version] of schemaResult.data.entries()) {
       const versionName = index === 0 ? Schema.VERSION_LATEST : Schema.dateToVersionString(version.date)
       versionStrings.push(versionName)
     }
@@ -65,11 +67,12 @@ export const SchemaAssets = (config: Config.Config): Vite.Plugin => {
       versions: versionStrings,
     }
 
-    debug(`schemaDataLoaded`, { versionCount: schemaData.length })
+    debug(`schemaDataLoaded`, { versionCount: schemaResult.data.length })
 
     return {
-      schemaData,
+      schemaData: schemaResult.data,
       metadata,
+      source: schemaResult.source,
     }
   })
 
@@ -102,10 +105,10 @@ export const SchemaAssets = (config: Config.Config): Vite.Plugin => {
 
   // Helper to write assets using schema-source API
   const writeDevAssets = async (
-    schemaData: Awaited<ReturnType<typeof Schema.readOrThrow>>,
+    schemaData: NonEmptyChangeSets,
     metadata: Schema.SchemaMetadata,
   ) => {
-    if (!schemaData) return
+    // schemaData is now guaranteed to be non-null NonEmptyChangeSets
 
     const devAssetsDir = config.paths.framework.devAssets.schemas
     await NodeFs.mkdir(devAssetsDir, { recursive: true })
@@ -149,6 +152,13 @@ export const SchemaAssets = (config: Config.Config): Vite.Plugin => {
         debug(`watchingSchemaFile`, { path: config.schema.dataSources.file.path })
       }
 
+      if (config.schema?.dataSources?.introspection?.url) {
+        // Watch the introspection file if introspection is configured
+        const introspectionFilePath = NodePath.join(config.paths.project.rootDir, `schema.introspection.json`)
+        server.watcher.add(introspectionFilePath)
+        debug(`watchingIntrospectionFile`, { path: introspectionFilePath })
+      }
+
       // Handle file removal
       server.watcher.on('unlink', async (file) => {
         const isSchemaFile = config.schema && (() => {
@@ -172,6 +182,15 @@ export const SchemaAssets = (config: Config.Config): Vite.Plugin => {
             if (absoluteFile.startsWith(absoluteSchemaDir + NodePath.sep)) return true
           }
 
+          // Check if file is the introspection file
+          if (config.schema.dataSources?.introspection?.url) {
+            const absoluteIntrospectionFile = NodePath.resolve(
+              config.paths.project.rootDir,
+              `schema.introspection.json`,
+            )
+            if (absoluteFile === absoluteIntrospectionFile) return true
+          }
+
           return false
         })()
 
@@ -181,14 +200,33 @@ export const SchemaAssets = (config: Config.Config): Vite.Plugin => {
           try {
             // Clear cache and regenerate
             loadAndProcessSchemaData.clear()
-            const { schemaData, metadata } = await loadAndProcessSchemaData()
-
-            if (schemaData) {
+            const { schemaData, metadata, source } = await loadAndProcessSchemaData()
+
+            // If file was deleted but can be recreated, attempt recreation
+            if (!schemaData && source.reCreate) {
+              debug(`attemptingSchemaRecreation`, { sourceType: source.type })
+              try {
+                const recreatedData = await source.reCreate()
+                if (recreatedData) {
+                  // Clear cache again and reload after recreation
+                  loadAndProcessSchemaData.clear()
+                  const reloadResult = await loadAndProcessSchemaData()
+                  if (reloadResult.schemaData) {
+                    await writeDevAssets(reloadResult.schemaData, reloadResult.metadata)
+                    debug(`hmr:schemaRecreatedAndWritten`, { versionCount: reloadResult.schemaData.length })
+                  }
+                } else {
+                  debug(`hmr:schemaRecreationFailed`, { reason: 'reCreate returned null' })
+                }
+              } catch (recreationError) {
+                debug(`hmr:schemaRecreationFailed`, { error: recreationError })
+              }
+            } else if (schemaData) {
               // Write new assets without the removed file
               await writeDevAssets(schemaData, metadata)
               debug(`hmr:schemaAssetsUpdatedAfterRemoval`, { versionCount: schemaData.length })
             } else {
-              // No schema data - clear all assets
+              // No schema data and cannot recreate - clear all assets
               const schemaSource = createDevSchemaSource({ hasSchema: false, versions: [] })
               await schemaSource.clearAllAssets()
               debug(`hmr:allAssetsCleared`, {})
@@ -274,6 +312,15 @@ export const SchemaAssets = (config: Config.Config): Vite.Plugin => {
           if (absoluteFile.startsWith(absoluteSchemaDir + NodePath.sep)) return true
         }
 
+        // Check if file is the introspection file
+        if (config.schema.dataSources?.introspection?.url) {
+          const absoluteIntrospectionFile = NodePath.resolve(
+            config.paths.project.rootDir,
+            `schema.introspection.json`,
+          )
+          if (absoluteFile === absoluteIntrospectionFile) return true
+        }
+
         return false
       })()
       if (isSchemaFile) {

package/src/cli/commands/open.ts

@@ -132,7 +132,7 @@ const wrapCache = <fn extends Fn.AnyAnyAsync>(fn: fn): fn => {
 
 // todo: use a proper validation, e.g. zod, better yet: allow to specify the validation in molt itself
 const parseHeaders = (headersJsonEncoded: string): Record<string, string> => {
-  const headersJson = Json.codec.deserialize(headersJsonEncoded)
+  const headersJson = Json.codec.decode(headersJsonEncoded)
   if (!Rec.is(headersJson)) {
     console.log(`--introspection-headers must be a JSON object.`)
     process.exit(1)

package/src/lib/grafaid/schema/schema.ts

@@ -4,6 +4,7 @@ export {
   buildASTSchema as fromAST,
   buildClientSchema as fromIntrospectionQuery,
   GraphQLSchema as Schema,
+  introspectionFromSchema as toIntrospectionQuery,
   printSchema as print,
 } from 'graphql'
 

package/src/lib/kit-temp.ts

@@ -105,9 +105,9 @@ export const objPolicyFilter = <
   const result: any = mode === `deny` ? { ...obj } : {}
 
   if (mode === `allow`) {
-    // For allow mode, only add specified keys
+    // For allow mode, only add specified keys that are own properties
     for (const key of keys) {
-      if (key in obj) {
+      if (Object.prototype.hasOwnProperty.call(obj, key)) {
         // @ts-expect-error
         result[key] = obj[key]
       }

package/src/lib/mask/$.test.ts

@@ -113,9 +113,9 @@ describe('property-based tests', () => {
           // Result contains only keys that were in both mask and object
           expect(resultKeys.every(key => keys.includes(key))).toBe(true)
 
-          // All requested keys that exist in obj are in result
+          // All requested keys that are own properties of obj are in result
           keys.forEach(key => {
-            if (key in obj) {
+            if (Object.prototype.hasOwnProperty.call(obj, key)) {
               expect(result).toHaveProperty(key, (obj as any)[key])
             }
           })
@@ -169,7 +169,7 @@ describe('property-based tests', () => {
           const result = Mask.apply(obj as any, Mask.create(keys))
 
           keys.forEach(key => {
-            if (key in obj) {
+            if (Object.prototype.hasOwnProperty.call(obj, key)) {
               expect(result).toHaveProperty(key)
               expect((result as any)[key]).toBe((obj as any)[key])
             }

package/src/lib/react-router-aid/react-router-aid.ts

@@ -1,4 +1,5 @@
 import type { ReactRouter } from '#dep/react-router/index'
+import type { React } from '#dep/react/index'
 import type { Http } from '@wollybeard/kit'
 
 export * from './get-paths-patterns.js'
@@ -18,23 +19,28 @@ export interface RouteHandle {
   statusCode?: Http.Status.Code.All
 }
 
-export const createRoute = <routeObject extends RouteObject>(
+export const route = <routeObject extends RouteObject>(
   routeObject: routeObject,
 ): routeObject => {
   return {
-    id: routeObject.path,
     ...routeObject,
   }
 }
 
-export type RouteObjectIndexInput = Omit<RouteObjectIndex, `index` | `children`>
+export type RouteObjectIndexInput = RouteObjectIndexInputConfig | React.ComponentType
+export type RouteObjectIndexInputConfig = Omit<RouteObjectIndex, `index` | `children`>
 
-export const createRouteIndex = (
-  indexRouteObjectInput: RouteObjectIndexInput,
+export const routeIndex = (
+  input: RouteObjectIndexInput,
 ): RouteObjectIndex => {
+  const routeConfig: RouteObjectIndexInputConfig = isComponentType(input) ? { Component: input } : input
   return {
-    ...indexRouteObjectInput,
+    ...routeConfig,
     index: true,
     children: undefined,
   }
 }
+
+const isComponentType = (value: unknown): value is React.ComponentType => {
+  return typeof value === 'function'
+}

package/src/template/components/GraphQLInteractive/lib/parser.ts

@@ -5,6 +5,7 @@
  * analysis to create unified tokens for interactive code blocks.
  */
 
+import { Api } from '#api/iso'
 import type { CodeAnnotation } from 'codehike/code'
 import {
   getNamedType,
@@ -14,7 +15,6 @@ import {
   GraphQLInputObjectType,
   GraphQLInterfaceType,
   GraphQLObjectType,
-  type GraphQLOutputType,
   GraphQLScalarType,
   type GraphQLSchema,
   GraphQLUnionType,
@@ -24,12 +24,7 @@ import {
 import graphqlWasmUrl from 'tree-sitter-graphql-grammar-wasm/grammar.wasm?url'
 import * as WebTreeSitter from 'web-tree-sitter'
 import treeSitterWasmUrl from 'web-tree-sitter/tree-sitter.wasm?url'
-import {
-  isKeywordNodeType,
-  isLiteralNodeType,
-  isPunctuationNodeType,
-  type TreeSitterGraphQLNodeType,
-} from './graphql-node-types.js'
+import { isKeywordNodeType, isPunctuationNodeType, type TreeSitterGraphQLNodeType } from './graphql-node-types.js'
 import type { SemanticNode } from './semantic-nodes.js'
 import {
   isArgument,
@@ -263,42 +258,63 @@ class UnifiedToken implements GraphQLToken {
 
     // Arguments - use #<field>__<argument> pattern
     if (isArgument(this.semantic)) {
-      return `/reference/${this.semantic.parentType.name}#${this.semantic.parentField.name}__${this.semantic.argumentDef.name}`
+      const basePath = Api.Schema.Routing.createReferencePath({
+        type: this.semantic.parentType.name,
+      })
+      return `${basePath}#${this.semantic.parentField.name}__${this.semantic.argumentDef.name}`
     }
 
     // Output fields - use hash links since field routes aren't connected yet
     if (isOutputField(this.semantic)) {
-      return `/reference/${this.semantic.parentType.name}#${this.semantic.fieldDef.name}`
+      const basePath = Api.Schema.Routing.createReferencePath({
+        type: this.semantic.parentType.name,
+      })
+      return `${basePath}#${this.semantic.fieldDef.name}`
     }
 
     // Input fields - use hash links since field routes aren't connected yet
     if (isInputField(this.semantic)) {
-      return `/reference/${this.semantic.parentType.name}#${this.semantic.fieldDef.name}`
+      const basePath = Api.Schema.Routing.createReferencePath({
+        type: this.semantic.parentType.name,
+      })
+      return `${basePath}#${this.semantic.fieldDef.name}`
     }
 
     // Type references - use :type pattern
     if (this.semantic instanceof GraphQLObjectType) {
-      return `/reference/${this.semantic.name}`
+      return Api.Schema.Routing.createReferencePath({
+        type: this.semantic.name,
+      })
     }
 
     if (this.semantic instanceof GraphQLScalarType) {
-      return `/reference/${this.semantic.name}`
+      return Api.Schema.Routing.createReferencePath({
+        type: this.semantic.name,
+      })
     }
 
     if (this.semantic instanceof GraphQLInterfaceType) {
-      return `/reference/${this.semantic.name}`
+      return Api.Schema.Routing.createReferencePath({
+        type: this.semantic.name,
+      })
     }
 
     if (this.semantic instanceof GraphQLUnionType) {
-      return `/reference/${this.semantic.name}`
+      return Api.Schema.Routing.createReferencePath({
+        type: this.semantic.name,
+      })
     }
 
     if (this.semantic instanceof GraphQLEnumType) {
-      return `/reference/${this.semantic.name}`
+      return Api.Schema.Routing.createReferencePath({
+        type: this.semantic.name,
+      })
     }
 
     if (this.semantic instanceof GraphQLInputObjectType) {
-      return `/reference/${this.semantic.name}`
+      return Api.Schema.Routing.createReferencePath({
+        type: this.semantic.name,
+      })
     }
 
     return null

package/src/template/components/HamburgerMenu.tsx

@@ -9,6 +9,7 @@ export interface HamburgerMenuProps {
   onToggle: () => void
   onClose: () => void
   sidebarData: Content.Item[]
+  basePath?: string
 }
 
 export const HamburgerMenu: React.FC<HamburgerMenuProps> = ({
@@ -16,6 +17,7 @@ export const HamburgerMenu: React.FC<HamburgerMenuProps> = ({
   onToggle,
   onClose,
   sidebarData,
+  basePath,
 }) => {
   // Prevent body scroll when mobile menu is open
   useEffect(() => {
@@ -87,7 +89,7 @@ export const HamburgerMenu: React.FC<HamburgerMenuProps> = ({
                 <Cross2Icon width='18' height='18' />
               </IconButton>
             </Flex>
-            <Sidebar data={sidebarData} />
+            <Sidebar data={sidebarData} basePath={basePath} />
           </Box>
         </>
       )}

package/src/template/components/ReferenceLink.tsx

@@ -1,3 +1,4 @@
+import { Api } from '#api/iso'
 import type { ReactNode } from 'react'
 import { useVersionPath } from '../hooks/useVersionPath.js'
 import { Link } from './Link.js'
@@ -21,10 +22,12 @@ interface Props {
 export const ReferenceLink = ({ type, field, children }: Props) => {
   const versionPath = useVersionPath()
 
-  let path = `/reference/${versionPath}${type}`
-  if (field) {
-    path += `/${field}`
-  }
+  const path = Api.Schema.Routing.joinSegmentsAndPaths(
+    Api.Schema.Routing.segmentLiterals.reference,
+    versionPath,
+    type,
+    field,
+  )
 
   return (
     <Link to={path}>

package/src/template/components/VersionSelector.tsx

@@ -1,13 +1,14 @@
+import { Api } from '#api/iso'
+import type { React } from '#dep/react/index'
 import { Select } from '@radix-ui/themes'
 import { useNavigate, useParams } from 'react-router'
-import { VERSION_LATEST } from '../lib/schema-utils/constants.js'
 
-interface VersionSelectorProps {
+interface Props {
   availableVersions: string[]
   currentVersion: string
 }
 
-export const VersionSelector = ({ availableVersions, currentVersion }: VersionSelectorProps) => {
+export const VersionSelector: React.FC<Props> = ({ availableVersions, currentVersion }) => {
   const navigate = useNavigate()
   const params = useParams()
 
@@ -17,20 +18,11 @@ export const VersionSelector = ({ availableVersions, currentVersion }: VersionSe
   }
 
   const handleVersionChange = (newVersion: string) => {
-    // Build new path preserving the current type/field if any
-    const currentType = params[`type`]
-    const currentField = params[`field`]
-
-    let newPath = `/reference`
-    if (newVersion !== VERSION_LATEST) {
-      newPath += `/version/${newVersion}`
-    }
-    if (currentType) {
-      newPath += `/${currentType}`
-      if (currentField) {
-        newPath += `/${currentField}`
-      }
-    }
+    const newPath = Api.Schema.Routing.createReferencePath({
+      version: newVersion,
+      type: params[`type`],
+      field: params[`field`],
+    })
 
     navigate(newPath)
   }
@@ -41,7 +33,7 @@ export const VersionSelector = ({ availableVersions, currentVersion }: VersionSe
       <Select.Content>
         {availableVersions.map(version => (
           <Select.Item key={version} value={version}>
-            {version === VERSION_LATEST ? `Latest` : version}
+            {version === Api.Schema.VERSION_LATEST ? `Latest` : version}
           </Select.Item>
         ))}
       </Select.Content>