polen 0.10.0 → 0.11.0-next.1

package/src/lib/graphql-change/change-groups.ts

@@ -1,3 +1,4 @@
+import { neverCase } from '@wollybeard/kit/language'
 import type {
   Change,
   DirectiveAddedChange,
@@ -248,3 +249,59 @@ export type DirectiveUsage =
   | DirectiveUsageInputFieldDefinitionRemovedChange
 
 export const isDirectiveUsage = (change: Change): change is DirectiveUsage => change.type.startsWith(`DIRECTIVE_USAGE_`)
+
+export type Type =
+  | 'TypeOperation'
+  | 'TypeDescription'
+  | 'FieldOperation'
+  | 'FieldDescription'
+  | 'FieldDeprecation'
+  | 'FieldDeprecationReason'
+  | 'FieldArgumentOperation'
+  | 'FieldArgument'
+  | 'FieldArgumentDescription'
+  | 'EnumValueOperation'
+  | 'EnumValueDescription'
+  | 'EnumValueDeprecationReason'
+  | 'InputFieldOperation'
+  | 'InputFieldDescription'
+  | 'InputFieldDefaultValue'
+  | 'UnionMemberOperation'
+  | 'ObjectTypeInterfaceOperation'
+  | 'DirectiveOperation'
+  | 'DirectiveDescription'
+  | 'DirectiveLocationOperation'
+  | 'DirectiveArgumentOperation'
+  | 'DirectiveArgument'
+  | 'DirectiveArgumentDescription'
+  | 'SchemaRootType'
+  | 'DirectiveUsage'
+
+export const getType = (change: Change): Type => {
+  if (isTypeOperation(change)) return 'TypeOperation'
+  if (isTypeDescription(change)) return 'TypeDescription'
+  if (isFieldOperation(change)) return 'FieldOperation'
+  if (isFieldDescription(change)) return 'FieldDescription'
+  if (isFieldDeprecation(change)) return 'FieldDeprecation'
+  if (isFieldDeprecationReason(change)) return 'FieldDeprecationReason'
+  if (isFieldArgumentOperation(change)) return 'FieldArgumentOperation'
+  if (isFieldArgument(change)) return 'FieldArgument'
+  if (isFieldArgumentDescription(change)) return 'FieldArgumentDescription'
+  if (isEnumValueOperation(change)) return 'EnumValueOperation'
+  if (isEnumValueDescription(change)) return 'EnumValueDescription'
+  if (isEnumValueDeprecationReason(change)) return 'EnumValueDeprecationReason'
+  if (isInputFieldOperation(change)) return 'InputFieldOperation'
+  if (isInputFieldDescription(change)) return 'InputFieldDescription'
+  if (isInputFieldDefaultValue(change)) return 'InputFieldDefaultValue'
+  if (isUnionMemberOperation(change)) return 'UnionMemberOperation'
+  if (isObjectTypeInterfaceOperation(change)) return 'ObjectTypeInterfaceOperation'
+  if (isDirectiveOperation(change)) return 'DirectiveOperation'
+  if (isDirectiveDescription(change)) return 'DirectiveDescription'
+  if (isDirectiveLocationOperation(change)) return 'DirectiveLocationOperation'
+  if (isDirectiveArgumentOperation(change)) return 'DirectiveArgumentOperation'
+  if (isDirectiveArgument(change)) return 'DirectiveArgument'
+  if (isDirectiveArgumentDescription(change)) return 'DirectiveArgumentDescription'
+  if (isSchemaRootType(change)) return 'SchemaRootType'
+  if (isDirectiveUsage(change)) return 'DirectiveUsage'
+  neverCase(change)
+}

package/src/lib/kit-temp.ts

@@ -181,6 +181,19 @@ export const ensureEnd = (string: string, ending: string) => {
   return string + ending
 }
 
+/**
+ * Create a generic cache with clear interface
+ */
+export const createCache = <T>() => {
+  const cache = new Map<string, T>()
+  return {
+    has: (key: string) => cache.has(key),
+    get: (key: string) => cache.get(key),
+    set: (key: string, value: T) => cache.set(key, value),
+    clear: () => cache.clear(),
+  }
+}
+
 export const ResponseInternalServerError = () =>
   new Response(null, {
     status: Http.Status.InternalServerError.code,

package/src/lib/path-map/$.test.ts

@@ -197,6 +197,22 @@ describe('PathMap', () => {
   })
 
   describe('property tests', () => {
+    // Helper to normalize base paths the same way PathMap.create does
+    const normalizeBasePath = (base: string): string => {
+      const trimmedBase = base.trim()
+      const collapsedBase = trimmedBase.replace(/\/+/g, '/')
+      const cleanedBase = collapsedBase === '/.' ? '/' : collapsedBase
+      return cleanedBase === '/' ? '/' : cleanedBase.replace(/\/$/, '')
+    }
+
+    // Helper to build absolute paths with proper handling of root base
+    const buildAbsolutePath = (normalizedBase: string, segments: string[]): string => {
+      if (segments.length === 0) return normalizedBase
+      return normalizedBase === '/'
+        ? `/${segments.join('/')}`
+        : `${normalizedBase}/${segments.join('/')}`
+    }
+
     // Arbitrary for valid path segments
     const pathSegment = fc.stringMatching(/^[a-zA-Z0-9_-]+$/)
 
@@ -243,10 +259,7 @@ describe('PathMap', () => {
       fc.assert(
         fc.property(pathInput, fc.string({ minLength: 1 }).filter(s => s.startsWith('/')), (input, base) => {
           const paths = PathMap.create(input, base)
-
-          // Base is normalized (trimmed, multiple slashes collapsed, trailing removed)
-          const collapsedBase = base.trim().replace(/\/+/g, '/')
-          const normalizedBase = collapsedBase === '/' ? '/' : collapsedBase.replace(/\/$/, '')
+          const normalizedBase = normalizeBasePath(base)
 
           function checkAbsolute(obj: any) {
             for (const [key, value] of Object.entries(obj)) {
@@ -278,14 +291,11 @@ describe('PathMap', () => {
             expect(JSON.stringify(p1.rooted)).toBe(JSON.stringify(p2.rooted))
 
             // Only absolute paths and base should change
-            const collapsedBase2 = base2.trim().replace(/\/+/g, '/')
-            const normalizedBase2 = collapsedBase2 === '/' ? '/' : collapsedBase2.replace(/\/$/, '')
-            expect(p2.base).toBe(normalizedBase2)
-
+            // Use the normalized base from the PathMap itself
             function checkBase(obj: any) {
               for (const [key, value] of Object.entries(obj)) {
                 if (typeof value === 'string') {
-                  expect(value.startsWith(normalizedBase2)).toBe(true)
+                  expect(value.startsWith(p2.base)).toBe(true)
                 } else if (typeof value === 'object') {
                   checkBase(value)
                 }
@@ -309,20 +319,13 @@ describe('PathMap', () => {
               if (currentPath.length === 0) {
                 expect(rel.$).toBe('.')
                 expect(rooted.$).toBe('.')
-                // Base is normalized in create() (trimmed, collapsed, trailing removed)
-                const collapsedBase = base.trim().replace(/\/+/g, '/')
-                const normalizedBase = collapsedBase === '/' ? '/' : collapsedBase.replace(/\/$/, '')
+                const normalizedBase = normalizeBasePath(base)
                 expect(abs.$).toBe(normalizedBase)
               } else {
                 expect(rel.$).toBe(currentPath[currentPath.length - 1])
                 expect(rooted.$).toBe(currentPath.join('/'))
-                // Handle base that might be '/' or have trailing slash
-                // Note: create() normalizes the base (trim + collapse + remove trailing)
-                const collapsedBase = base.trim().replace(/\/+/g, '/')
-                const normalizedBase = collapsedBase === '/' ? '/' : collapsedBase.replace(/\/$/, '')
-                const expectedAbs = normalizedBase === '/'
-                  ? `/${currentPath.join('/')}`
-                  : `${normalizedBase}/${currentPath.join('/')}`
+                const normalizedBase = normalizeBasePath(base)
+                const expectedAbs = buildAbsolutePath(normalizedBase, currentPath)
                 expect(abs.$).toBe(expectedAbs)
               }
             }

package/src/lib/path-map/path-map.ts

@@ -113,7 +113,9 @@ export function create<T extends PathInput>(paths: T, base?: string): RelativePa
   const trimmedBase = base.trim()
   // Collapse multiple slashes to single, then remove trailing (unless it's just "/")
   const collapsedBase = trimmedBase.replace(/\/+/g, `/`)
-  const normalizedBase = collapsedBase === `/` ? `/` : collapsedBase.replace(/\/$/, ``)
+  // Handle edge case where base is "/." - this should become "/"
+  const cleanedBase = collapsedBase === `/.` ? `/` : collapsedBase
+  const normalizedBase = cleanedBase === `/` ? `/` : cleanedBase.replace(/\/$/, ``)
 
   const rooted = processRootedPaths(paths, [])
   const absolute = processAbsolutePaths(paths, normalizedBase, [])

package/src/project-data.ts

@@ -1,18 +1,10 @@
 import type { Config } from '#api/config/index'
 import type { NavbarItem } from '#api/content/navbar'
-import type { Schema } from './api/schema/index.js'
 
 export interface ProjectData {
-  schema: null | Schema.Schema
   basePath: string
-  paths: Config.Config[`paths`][`project`]
+  paths: Config.Config['paths']
   navbar: NavbarItem[]
-  server: {
-    port: number
-    static: {
-      directory: string
-      route: string
-    }
-  }
-  warnings: Config.Config[`warnings`]
+  server: Config.Config['server']
+  warnings: Config.Config['warnings']
 }

package/src/template/components/Changelog.tsx

@@ -1,15 +1,14 @@
-import type { GrafaidOld } from '#lib/grafaid-old/index'
+import type { Api } from '#api/index'
 import { CRITICALITY_LEVELS } from '#lib/graphql-change/criticality'
 import { GraphqlChange } from '#lib/graphql-change/index'
 import type { GraphqlChangeset } from '#lib/graphql-changeset/index'
 import type { CriticalityLevel } from '@graphql-inspector/core'
 import { Box } from '@radix-ui/themes'
-import { neverCase } from '@wollybeard/kit/language'
-import type React from 'react'
+import React from 'react'
 import { useMemo } from 'react'
-import type { Schema as ChangelogData } from '../../api/schema/index.js'
 import { CriticalitySection } from './Changelog/CriticalitySection.js'
 import * as Group from './Changelog/groups/index.js'
+import { ComponentDispatch } from './ComponentDispatch.js'
 
 export const renderDate = (date: Date) => {
   return date.toLocaleString(`default`, {
@@ -20,10 +19,10 @@ export const renderDate = (date: Date) => {
   })
 }
 
-export const Changelog: React.FC<{ schema: ChangelogData.Schema }> = ({ schema }) => {
+export const Changelog: React.FC<{ changesets: Api.Schema.NonEmptyChangeSets }> = ({ changesets }) => {
   return (
     <Box>
-      {schema.versions.map(changeset => <Changeset key={changeset.date.toISOString()} changeset={changeset} />)}
+      {changesets.map(changeset => <Changeset key={changeset.date.toISOString()} changeset={changeset} />)}
     </Box>
   )
 }
@@ -62,69 +61,19 @@ const Changeset: React.FC<{ changeset: GraphqlChangeset.ChangeSet }> = ({ change
       </h1>
       {groupedChanges.map(group => (
         <CriticalitySection key={group.level} level={group.level} changes={group.changes}>
-          {group.changes.map(change => (
-            <Change key={`${change.type}-${change.path || change.message}`} change={change} schema={changeset.after} />
-          ))}
+          {group.changes.map(change => {
+            const type = GraphqlChange.Group.getType(change)
+            return (
+              <ComponentDispatch
+                key={`${change.type}-${change.path || change.message}`}
+                components={Group}
+                name={type}
+                props={{ change }}
+              />
+            )
+          })}
         </CriticalitySection>
       ))}
     </Box>
   )
 }
-
-const Change: React.FC<{ change: GraphqlChange.Change; schema: GrafaidOld.Schema.Schema }> = (
-  { change, schema },
-) => {
-  if (GraphqlChange.Group.isTypeOperation(change)) {
-    return <Group.TypeOperation change={change} />
-  } else if (GraphqlChange.Group.isTypeDescription(change)) {
-    return <Group.TypeDescription change={change} />
-  } else if (GraphqlChange.Group.isFieldOperation(change)) {
-    return <Group.FieldOperation change={change} />
-  } else if (GraphqlChange.Group.isFieldDescription(change)) {
-    return <Group.FieldDescription change={change} />
-  } else if (GraphqlChange.Group.isFieldDeprecation(change)) {
-    return <Group.FieldDeprecation change={change} />
-  } else if (GraphqlChange.Group.isFieldDeprecationReason(change)) {
-    return <Group.FieldDeprecationReason change={change} />
-  } else if (GraphqlChange.Group.isFieldArgumentOperation(change)) {
-    return <Group.FieldArgumentOperation change={change} />
-  } else if (GraphqlChange.Group.isFieldArgument(change)) {
-    return <Group.FieldArgument change={change} />
-  } else if (GraphqlChange.Group.isFieldArgumentDescription(change)) {
-    return <Group.FieldArgumentDescription change={change} />
-  } else if (GraphqlChange.Group.isEnumValueOperation(change)) {
-    return <Group.EnumValueOperation change={change} />
-  } else if (GraphqlChange.Group.isEnumValueDescription(change)) {
-    return <Group.EnumValueDescription change={change} />
-  } else if (GraphqlChange.Group.isEnumValueDeprecationReason(change)) {
-    return <Group.EnumValueDeprecationReason change={change} />
-  } else if (GraphqlChange.Group.isInputFieldOperation(change)) {
-    return <Group.InputFieldOperation change={change} />
-  } else if (GraphqlChange.Group.isInputFieldDescription(change)) {
-    return <Group.InputFieldDescription change={change} />
-  } else if (GraphqlChange.Group.isInputFieldDefaultValue(change)) {
-    return <Group.InputFieldDefaultValue change={change} />
-  } else if (GraphqlChange.Group.isUnionMemberOperation(change)) {
-    return <Group.UnionMemberOperation change={change} />
-  } else if (GraphqlChange.Group.isObjectTypeInterfaceOperation(change)) {
-    return <Group.ObjectTypeInterfaceOperation change={change} />
-  } else if (GraphqlChange.Group.isDirectiveOperation(change)) {
-    return <Group.DirectiveOperation change={change} />
-  } else if (GraphqlChange.Group.isDirectiveDescription(change)) {
-    return <Group.DirectiveDescription change={change} />
-  } else if (GraphqlChange.Group.isDirectiveLocationOperation(change)) {
-    return <Group.DirectiveLocationOperation change={change} />
-  } else if (GraphqlChange.Group.isDirectiveArgumentOperation(change)) {
-    return <Group.DirectiveArgumentOperation change={change} />
-  } else if (GraphqlChange.Group.isDirectiveArgument(change)) {
-    return <Group.DirectiveArgument change={change} />
-  } else if (GraphqlChange.Group.isDirectiveArgumentDescription(change)) {
-    return <Group.DirectiveArgumentDescription change={change} />
-  } else if (GraphqlChange.Group.isSchemaRootType(change)) {
-    return <Group.SchemaRootType change={change} />
-  } else if (GraphqlChange.Group.isDirectiveUsage(change)) {
-    return <Group.DirectiveUsage change={change} />
-  } else {
-    neverCase(change)
-  }
-}

package/src/template/components/CodeBlock.tsx

@@ -1,23 +1,21 @@
 import { type HighlightedCode, Pre } from 'codehike/code'
+import type { GraphQLSchema } from 'graphql'
 import React from 'react'
 import PROJECT_DATA from 'virtual:polen/project/data.jsonsuper'
 import { GraphQLInteractive } from './GraphQLInteractive/index.js'
 
 interface CodeBlockProps {
   codeblock: HighlightedCode
+  schema?: GraphQLSchema
 }
 
 /**
  * Code block component for Code Hike
  * Handles pre-highlighted code blocks and interactive GraphQL blocks
  */
-export const CodeBlock: React.FC<CodeBlockProps> = ({ codeblock }) => {
+export const CodeBlock: React.FC<CodeBlockProps> = ({ codeblock, schema }) => {
   // Check if this is an interactive GraphQL block
   if (codeblock.lang === 'graphql' && codeblock.meta?.includes('interactive')) {
-    const schema = typeof window !== 'undefined'
-      ? (window as any).__POLEN_GRAPHQL_SCHEMA__
-      : null
-
     return (
       <GraphQLInteractive
         codeblock={codeblock}

package/src/template/components/ComponentDispatch.tsx

@@ -0,0 +1,42 @@
+import React from 'react'
+
+/**
+ * A generic component dispatcher that dynamically renders components from a namespace.
+ *
+ * Useful for cases where you need to select and render a component at runtime based on
+ * a string key, while maintaining some level of type safety through generics.
+ *
+ * @template TComponents - The object/namespace containing the components
+ * @template TName - The key type for component selection (constrained to keyof TComponents)
+ *
+ * @param components - The namespace/object containing the components to choose from
+ * @param name - The key to select which component to render
+ * @param props - The props to pass to the selected component
+ *
+ * @example
+ * ```tsx
+ * import * as MyComponents from './MyComponents'
+ *
+ * const componentName = getComponentName(data)
+ * return (
+ *   <ComponentDispatch
+ *     components={MyComponents}
+ *     name={componentName}
+ *     props={{ data }}
+ *   />
+ * )
+ * ```
+ */
+export const ComponentDispatch = <
+  TComponents extends Record<string, React.ComponentType<any>>,
+  TName extends keyof TComponents,
+>(
+  { components, name, props }: {
+    components: TComponents
+    name: TName
+    props: object
+  },
+) => {
+  const Component = components[name]
+  return React.createElement(Component as any, props)
+}

package/src/template/components/ReferenceLink.tsx

@@ -0,0 +1,34 @@
+import type { ReactNode } from 'react'
+import { useVersionPath } from '../hooks/useVersionPath.js'
+import { Link } from './Link.js'
+
+interface Props {
+  /** The GraphQL type name */
+  type: string
+  /** Optional field name for field-specific links */
+  field?: string
+  /** Link content */
+  children: ReactNode
+}
+
+/**
+ * Link component for GraphQL schema references that preserves version context
+ *
+ * @example
+ * <ReferenceLink type="User">User</ReferenceLink>
+ * <ReferenceLink type="User" field="name">User.name</ReferenceLink>
+ */
+export const ReferenceLink = ({ type, field, children }: Props) => {
+  const versionPath = useVersionPath()
+
+  let path = `/reference/${versionPath}${type}`
+  if (field) {
+    path += `/${field}`
+  }
+
+  return (
+    <Link to={path}>
+      {children}
+    </Link>
+  )
+}

package/src/template/components/TypeAnnotation.tsx

@@ -2,7 +2,7 @@ import { Text } from '@radix-ui/themes'
 import type { GraphQLType } from 'graphql'
 import { isInputObjectType, isListType, isNamedType, isNonNullType, isScalarType } from 'graphql'
 import type { FC } from 'react'
-import { Link } from './Link.js'
+import { ReferenceLink } from './ReferenceLink.js'
 
 export interface Props {
   type: GraphQLType // Can be either GraphQLInputType or GraphQLOutputType
@@ -40,20 +40,18 @@ export const TypeAnnotation: FC<Props> = ({ type }) => {
     // Handle input object types
     if (isInputObjectType(namedType)) {
       return (
-        <Link
-          to={`/reference/${namedType.name}`}
-        >
+        <ReferenceLink type={namedType.name}>
           <Text color='green'>{namedType.name}</Text>
-        </Link>
+        </ReferenceLink>
       )
     }
 
     // If it's an expandable type (object or interface), make it a link
     // if (Grafaid.isExpandableType(namedType)) {
     return (
-      <Link to={`/reference/${namedType.name}`}>
+      <ReferenceLink type={namedType.name}>
         <Text color={isScalarType(namedType) ? `purple` : `blue`}>{namedType.name}</Text>
-      </Link>
+      </ReferenceLink>
     )
 
     // For scalar and other non-expandable types, just render the name

package/src/template/components/TypeFieldsLinkList.tsx

@@ -1,7 +1,7 @@
 import { Box, Flex, Heading } from '@radix-ui/themes'
 import type { GraphQLInterfaceType, GraphQLObjectType } from 'graphql'
 import type { FC } from 'react'
-import { Link } from './Link.js'
+import { ReferenceLink } from './ReferenceLink.js'
 
 export interface Props {
   type: GraphQLObjectType | GraphQLInterfaceType
@@ -9,27 +9,24 @@ export interface Props {
 
 export const TypeFieldsLinkList: FC<Props> = ({ type }) => {
   return (
-    (
-      <Box>
-        <Heading>{type.name}</Heading>
-        <Flex direction='column'>
-          {Object.values(type.getFields()).map(field => {
-            return (
-              (
-                <Box key={field.name}>
-                  <Link
-                    to={`/reference/${type.name}/${field.name}`}
-                    // TODO: can we use styled from Radix?
-                    // activeProps={{ style: { fontWeight: `bold` } }}
-                  >
-                    {field.name}
-                  </Link>
-                </Box>
-              )
-            )
-          })}
-        </Flex>
-      </Box>
-    )
+    <Box>
+      <Heading>{type.name}</Heading>
+      <Flex direction='column'>
+        {Object.values(type.getFields()).map(field => {
+          return (
+            <Box key={field.name}>
+              <ReferenceLink
+                type={type.name}
+                field={field.name}
+                // TODO: can we use styled from Radix?
+                // activeProps={{ style: { fontWeight: `bold` } }}
+              >
+                {field.name}
+              </ReferenceLink>
+            </Box>
+          )
+        })}
+      </Flex>
+    </Box>
   )
 }

package/src/template/components/TypeIndex.tsx

@@ -3,7 +3,7 @@ import { Box, Flex, Heading } from '@radix-ui/themes'
 import { Obj } from '@wollybeard/kit'
 import type { GraphQLNamedType, GraphQLSchema } from 'graphql'
 import type { FC } from 'react'
-import { Link } from './Link.js'
+import { ReferenceLink } from './ReferenceLink.js'
 
 export interface Props {
   schema: GraphQLSchema
@@ -31,16 +31,14 @@ const TypeSection: FC<{ title: string; types: GraphQLNamedType[] }> = ({ title,
 
 const TypeList: FC<{ types: GraphQLNamedType[] }> = ({ types }) => {
   return (
-    (
-      <Box>
-        {types.map(type => (
-          <Box key={type.name}>
-            <Link to={`/reference/${type.name}`}>
-              {type.name}
-            </Link>
-          </Box>
-        ))}
-      </Box>
-    )
+    <Box>
+      {types.map(type => (
+        <Box key={type.name}>
+          <ReferenceLink type={type.name}>
+            {type.name}
+          </ReferenceLink>
+        </Box>
+      ))}
+    </Box>
   )
 }

package/src/template/components/VersionSelector.tsx

@@ -0,0 +1,50 @@
+import { Select } from '@radix-ui/themes'
+import { useNavigate, useParams } from 'react-router'
+import { VERSION_LATEST } from '../lib/schema-utils/constants.js'
+
+interface VersionSelectorProps {
+  availableVersions: string[]
+  currentVersion: string
+}
+
+export const VersionSelector = ({ availableVersions, currentVersion }: VersionSelectorProps) => {
+  const navigate = useNavigate()
+  const params = useParams()
+
+  // Don't show selector if only one version
+  if (availableVersions.length <= 1) {
+    return null
+  }
+
+  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}`
+      }
+    }
+
+    navigate(newPath)
+  }
+
+  return (
+    <Select.Root value={currentVersion} onValueChange={handleVersionChange}>
+      <Select.Trigger />
+      <Select.Content>
+        {availableVersions.map(version => (
+          <Select.Item key={version} value={version}>
+            {version === VERSION_LATEST ? `Latest` : version}
+          </Select.Item>
+        ))}
+      </Select.Content>
+    </Select.Root>
+  )
+}

package/src/template/components/graphql/type-link.tsx

@@ -1,18 +1,19 @@
 import { Grafaid } from '#lib/grafaid/index'
 import { Code, Flex } from '@radix-ui/themes'
-import { Link } from '../Link.js'
+import { ReferenceLink } from '../ReferenceLink.js'
 import { TypeKindIcon } from './graphql.js'
 import { typeKindTokensIndex } from './type-kind-tokens.js'
 
 export const TypeLink: React.FC<{ type: Grafaid.Schema.TypesLike.Named }> = ({ type }) => {
   const kind = Grafaid.Schema.typeKindFromClass(type)
+
   return (
-    <Link to={`/reference/${type.name}`}>
+    <ReferenceLink type={type.name}>
       <Flex align='center' gap='1' display='inline-flex'>
         <TypeKindIcon kind={kind} />
         {` `}
         <Code color={typeKindTokensIndex[kind].color} variant='ghost'>{type.name}</Code>
       </Flex>
-    </Link>
+    </ReferenceLink>
   )
 }

package/src/template/hooks/useVersionPath.ts

@@ -0,0 +1,10 @@
+import { useParams } from 'react-router'
+
+/**
+ * Custom hook to generate version path for versioned routes
+ * Returns the appropriate path prefix for the current version
+ */
+export const useVersionPath = (): string => {
+  const params = useParams()
+  return params[`version`] ? `version/${params[`version`]}/` : ``
+}

package/src/template/{components → layouts}/ChangelogLayout.tsx

@@ -8,7 +8,7 @@ import type { GraphqlChangeset } from '#lib/graphql-changeset/index'
 import { Box, Flex, Text } from '@radix-ui/themes'
 import type React from 'react'
 import { useEffect, useState } from 'react'
-import { renderDate } from './Changelog.js'
+import { renderDate } from '../components/Changelog.js'
 
 interface ChangelogLayoutProps {
   children: React.ReactNode

package/src/template/layouts/index.ts

@@ -1 +1,2 @@
+export * from './ChangelogLayout.js'
 export * from './SidebarLayout.js'

package/src/template/lib/fetch-text.ts

@@ -0,0 +1,13 @@
+/**
+ * Fetch text content from a URL
+ * @param url - The URL to fetch from
+ * @returns Promise that resolves to the text content
+ * @throws Error if the request fails
+ */
+export const fetchText = async (url: string): Promise<string> => {
+  const response = await fetch(url)
+  if (!response.ok) {
+    throw new Error(`Failed to fetch: ${url} (${response.status} ${response.statusText})`)
+  }
+  return response.text()
+}