polen 0.10.0 → 0.11.0-next.2

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()
+}

package/src/template/lib/polen-url.ts

@@ -33,3 +33,23 @@ export const polenUrlPath = (...segments: string[]): string => {
 
   return basePath + path
 }
+
+/**
+ * Create a Polen URL path for assets.
+ *
+ * This is a convenience wrapper around `polenUrlPath` that automatically
+ * prepends the assets root path.
+ *
+ * @param segments - Path segments within the assets directory
+ * @returns Full URL path to the asset
+ *
+ * @example
+ * polenUrlPathAssets('schemas', 'latest.json') // '/demos/pokemon/assets/schemas/latest.json'
+ * polenUrlPathAssets('images/logo.png') // '/demos/pokemon/assets/images/logo.png'
+ */
+export const polenUrlPathAssets = (...segments: string[]): string => {
+  return polenUrlPath(
+    PROJECT_DATA.server.routes.assets,
+    ...segments,
+  )
+}

package/src/template/lib/schema-utils/constants.ts

@@ -0,0 +1,4 @@
+/**
+ * Re-exports of schema constants for template usage
+ */
+export { dateToVersionString, VERSION_LATEST } from '#api/schema/schema'

package/src/template/lib/schema-utils/schema-utils.ts

@@ -0,0 +1,42 @@
+import { buildSchema, print } from 'graphql'
+import type { DocumentNode, GraphQLSchema } from 'graphql'
+
+/**
+ * Convert a GraphQL AST back to a GraphQL Schema object
+ */
+export const astToSchema = (ast: DocumentNode): GraphQLSchema => {
+  // Convert AST back to SDL string
+  const sdl = print(ast)
+  // Build schema from SDL
+  return buildSchema(sdl)
+}
+
+/**
+ * Simple cache for loaded schemas to avoid repeated conversions
+ */
+export const createSchemaCache = () => {
+  const cache = new Map<string, GraphQLSchema>()
+
+  return {
+    get(version: string): GraphQLSchema | undefined {
+      return cache.get(version)
+    },
+
+    set(version: string, schema: GraphQLSchema): void {
+      // Limit cache size to prevent memory issues
+      if (cache.size >= 10) {
+        const firstKey = cache.keys().next().value
+        if (firstKey) cache.delete(firstKey)
+      }
+      cache.set(version, schema)
+    },
+
+    has(version: string): boolean {
+      return cache.has(version)
+    },
+
+    clear(): void {
+      cache.clear()
+    },
+  }
+}

package/src/template/routes/changelog.tsx

@@ -1,25 +1,34 @@
+import type { GraphqlChangeset } from '#lib/graphql-changeset/index'
 import { createRoute } from '#lib/react-router-aid/react-router-aid'
 import { createLoader, useLoaderData } from '#lib/react-router-loader/react-router-loader'
-import PROJECT_DATA from 'virtual:polen/project/data.jsonsuper'
 import { Changelog } from '../components/Changelog.js'
-import { ChangelogLayout } from '../components/ChangelogLayout.js'
+import { ChangelogLayout } from '../layouts/index.js'
+import { schemaSource } from '../sources/schema-source.js'
+
+const loader = createLoader(async () => {
+  // Check if schema exists first
+  if (schemaSource.isEmpty) {
+    return { changesets: [] }
+  }
+
+  // Fetch all changesets with before/after/changes data
+  const changesets = await schemaSource.getAllChangesets()
 
-const loader = createLoader(() => {
   return {
-    schema: PROJECT_DATA.schema,
+    changesets,
   }
 })
 
 const Component = () => {
   const data = useLoaderData<typeof loader>()
 
-  if (!data.schema) {
-    return <div>No data to show. There is no schema is.</div>
+  if (data.changesets.length === 0) {
+    return <div>No schema versions available for changelog.</div>
   }
 
   return (
-    <ChangelogLayout versions={data.schema.versions}>
-      <Changelog schema={data.schema} />
+    <ChangelogLayout versions={data.changesets}>
+      <Changelog changesets={data.changesets as [GraphqlChangeset.ChangeSet, ...GraphqlChangeset.ChangeSet[]]} />
     </ChangelogLayout>
   )
 }

package/src/template/routes/pages.tsx

@@ -0,0 +1,109 @@
+import { createRoute } from '#lib/react-router-aid/react-router-aid'
+import { createLoader, useLoaderData } from '#lib/react-router-loader/react-router-loader'
+import { SidebarLayout } from '#template/layouts/index'
+import { MDXProvider } from '@mdx-js/react'
+import {
+  Badge,
+  Box,
+  Button,
+  Callout,
+  Card,
+  Code,
+  DataList,
+  Em,
+  Heading,
+  Link,
+  Quote,
+  Separator,
+  Strong,
+  Table,
+  Tabs,
+  Text,
+  Tooltip,
+} from '@radix-ui/themes'
+import { Outlet, useLocation } from 'react-router'
+import PROJECT_DATA_PAGES_CATALOG from 'virtual:polen/project/data/pages-catalog.jsonsuper'
+import { routes } from 'virtual:polen/project/routes.jsx'
+import { CodeBlock } from '../components/CodeBlock.js'
+import { schemaSource } from '../sources/schema-source.js'
+
+const loader = createLoader(async () => {
+  // Check if schema exists first
+  if (schemaSource.isEmpty) {
+    return { schema: null }
+  }
+
+  // Fetch the latest schema for MDX pages
+  const schema = await schemaSource.get('latest')
+  return { schema }
+})
+
+const Component = () => {
+  const { schema } = useLoaderData<typeof loader>()
+  const location = useLocation()
+
+  // Build sidebar from pages catalog
+  // Get the top-level path segment (e.g., '/guide/foo' -> '/guide')
+  const pathSegments = location.pathname.split('/').filter(Boolean)
+  const topLevelPath = pathSegments[0] ? `/${pathSegments[0]}` : '/'
+
+  // Get the sidebar for this section
+  const sidebar = PROJECT_DATA_PAGES_CATALOG.sidebarIndex[topLevelPath]?.items || []
+
+  return (
+    <MDXProvider
+      components={{
+        // Map markdown elements to Radix with spacing
+        p: (props) => <Text as='p' mb='4' {...props} />,
+        h1: (props) => <Heading size='8' mt='6' mb='4' {...props} />,
+        h2: (props) => <Heading size='7' mt='6' mb='3' {...props} />,
+        h3: (props) => <Heading size='6' mt='5' mb='3' {...props} />,
+        h4: (props) => <Heading size='5' mt='5' mb='2' {...props} />,
+        h5: (props) => <Heading size='4' mt='4' mb='2' {...props} />,
+        h6: (props) => <Heading size='3' mt='4' mb='2' {...props} />,
+        strong: Strong,
+        em: Em,
+        code: Code,
+        blockquote: (props) => <Quote my='4' {...props} />,
+        a: Link,
+        hr: (props) => <Separator my='6' {...props} />,
+        table: Table.Root,
+        thead: Table.Header,
+        tbody: Table.Body,
+        tr: Table.Row,
+        th: Table.ColumnHeaderCell,
+        td: Table.Cell,
+        // Lists need spacing too
+        ul: (props) => <Box as='ul' mb='4' style={{ paddingLeft: '1.5rem' }} {...props} />,
+        ol: (props) => <Box as='ol' mb='4' style={{ paddingLeft: '1.5rem' }} {...props} />,
+        li: (props) => <Box as='li' mb='2' {...props} />,
+
+        // Direct Radix components for MDX
+        Badge,
+        Button,
+        // @ts-expect-error
+        Callout,
+        Card,
+        // @ts-expect-error
+        DataList,
+        // @ts-expect-error
+        Tabs,
+        Tooltip,
+
+        // Code Hike component with schema injected
+        CodeBlock: (props: any) => <CodeBlock {...props} schema={schema} />,
+      }}
+    >
+      <SidebarLayout sidebar={sidebar}>
+        <Outlet />
+      </SidebarLayout>
+    </MDXProvider>
+  )
+}
+
+export const pages = createRoute({
+  // Pathless layout route - doesn't affect URL paths
+  loader,
+  Component,
+  children: [...routes], // All MDX page routes go here
+})

package/src/template/routes/reference.$type.$field.tsx

@@ -29,6 +29,6 @@ const Component = () => {
 }
 
 export const reference$type$field = ReactRouterAid.createRoute({
-  path: `:type/:field`,
+  path: `:field`,
   Component,
 })

package/src/template/routes/reference.$type.tsx

@@ -3,6 +3,7 @@ import { useLoaderData } from '#lib/react-router-loader/react-router-loader'
 import { useParams } from 'react-router'
 import { MissingSchema } from '../components/MissingSchema.js'
 import { NamedType } from '../components/NamedType.js'
+import { reference$type$field } from './reference.$type.$field.js'
 import type { reference } from './reference.js'
 
 const Component = () => {
@@ -24,4 +25,5 @@ const Component = () => {
 export const reference$type = createRoute({
   path: `:type`,
   Component,
+  children: [reference$type$field],
 })