polen 0.10.0 → 0.11.0-next.1

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],
 })

package/src/template/routes/reference.tsx

@@ -2,16 +2,30 @@ import type { Content } from '#api/content/$'
 import { GrafaidOld } from '#lib/grafaid-old/index'
 import { createRoute } from '#lib/react-router-aid/react-router-aid'
 import { createLoader, useLoaderData } from '#lib/react-router-loader/react-router-loader'
+import { Box } from '@radix-ui/themes'
 import { Outlet } from 'react-router'
-import PROJECT_DATA from 'virtual:polen/project/data.jsonsuper'
 import { MissingSchema } from '../components/MissingSchema.js'
+import { VersionSelector } from '../components/VersionSelector.js'
+import { useVersionPath } from '../hooks/useVersionPath.js'
 import { SidebarLayout } from '../layouts/index.js'
+import { VERSION_LATEST } from '../lib/schema-utils/constants.js'
+import { schemaSource } from '../sources/schema-source.js'
 import { reference$type } from './reference.$type.js'
+import { referenceVersion$version$type } from './reference.version.$version.$type.js'
+
+const loader = createLoader(async ({ params }) => {
+  // Handle both versioned and unversioned routes:
+  // - Versioned: /reference/version/:version/:type → params.version exists
+  // - Unversioned: /reference/:type → params.version is undefined, defaults to latest
+  const currentVersion = params.version ?? VERSION_LATEST
+
+  const schema = await schemaSource.get(currentVersion)
+  const availableVersions = schemaSource.versions
 
-const loader = createLoader(() => {
-  const latestSchemaVersion = PROJECT_DATA.schema?.versions[0].after ?? null
   return {
-    schema: latestSchemaVersion,
+    schema,
+    currentVersion,
+    availableVersions,
   }
 })
 
@@ -28,6 +42,9 @@ const Component = () => {
   const sidebarItems: Content.Item[] = []
   const kindEntries = Object.entries(kindMap.list).filter(([_, types]) => types.length > 0)
 
+  // Build path prefix based on current version using new route structure
+  const versionPath = useVersionPath()
+
   for (const [title, types] of kindEntries) {
     sidebarItems.push({
       type: `ItemSection` as const,
@@ -37,21 +54,36 @@ const Component = () => {
       links: types.map(type => ({
         type: `ItemLink` as const,
         title: type.name,
-        pathExp: `reference/${type.name}`,
+        pathExp: `reference/${versionPath}${type.name}`,
       })),
     })
   }
 
   return (
     <SidebarLayout sidebar={sidebarItems}>
+      <Box mb={`4`}>
+        <VersionSelector
+          availableVersions={data.availableVersions}
+          currentVersion={data.currentVersion}
+        />
+      </Box>
       <Outlet />
     </SidebarLayout>
   )
 }
 
+// Create the versioned reference route with explicit version prefix
+const referenceVersioned = createRoute({
+  path: `version/:version`,
+  loader,
+  Component,
+  children: [referenceVersion$version$type],
+})
+
+// Create the main reference route with explicit version path and fallback type path
 export const reference = createRoute({
   path: `reference`,
   loader,
   Component,
-  children: [reference$type],
+  children: [referenceVersioned, reference$type],
 })

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

@@ -0,0 +1,35 @@
+import { Grafaid } from '#lib/grafaid/index'
+import { createRoute } from '#lib/react-router-aid/react-router-aid'
+import { useLoaderData } from '#lib/react-router-loader/react-router-loader'
+import { useParams } from 'react-router'
+import { Field } from '../components/Field.js'
+import { MissingSchema } from '../components/MissingSchema.js'
+import type { reference } from './reference.js'
+
+const Component = () => {
+  const params = useParams() as { type: string; field: string; version: string }
+  const data = useLoaderData<typeof reference.loader>(`reference`)
+  if (!data.schema) {
+    return <MissingSchema />
+  }
+
+  const type = data.schema.getType(params.type)
+  if (!type) return `Could not find type ${params.type}`
+  if (!Grafaid.Schema.TypesLike.isFielded(type)) {
+    return `Type ${params.type} does not have fields`
+  }
+
+  const fields = type.getFields()
+  const field = fields[params.field]
+  if (!field) {
+    return `Could not find field ${params.field} on type ${params.type}`
+  }
+
+  return <Field data={field} />
+}
+
+export const referenceVersion$version$type$field = createRoute({
+  id: `reference-version-type-field`,
+  path: `:field`,
+  Component,
+})

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

@@ -0,0 +1,30 @@
+import { createRoute } from '#lib/react-router-aid/react-router-aid'
+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 type { reference } from './reference.js'
+import { referenceVersion$version$type$field } from './reference.version.$version.$type.$field.js'
+
+const Component = () => {
+  const params = useParams() as { type: string; version: string }
+
+  const data = useLoaderData<typeof reference.loader>(`reference`)
+  if (!data.schema) {
+    return <MissingSchema />
+  }
+
+  const type = data.schema.getType(params.type)
+  if (!type) {
+    return <div>Type not found: {params.type}</div>
+  }
+
+  return <NamedType data={type} />
+}
+
+export const referenceVersion$version$type = createRoute({
+  id: `reference-version-type`,
+  path: `:type`,
+  Component,
+  children: [referenceVersion$version$type$field],
+})

package/src/template/routes/root.tsx

@@ -1,38 +1,12 @@
 import type { ReactRouter } from '#dep/react-router/index'
 import { createRoute } from '#lib/react-router-aid/react-router-aid'
-import { SidebarLayout } from '#template/layouts/index'
-import { MDXProvider } from '@mdx-js/react'
-import {
-  Badge,
-  Box,
-  Button,
-  Callout,
-  Card,
-  Code,
-  DataList,
-  Em,
-  Flex,
-  Heading,
-  Link,
-  Quote,
-  Separator,
-  Strong,
-  Table,
-  Tabs,
-  Text,
-  Theme,
-  Tooltip,
-} from '@radix-ui/themes'
-import { Link as LinkReactRouter, useLocation } from 'react-router'
+import { Box, Flex, Theme } from '@radix-ui/themes'
+import { Link as LinkReactRouter } from 'react-router'
 import { Outlet, ScrollRestoration } from 'react-router'
 import logoSrc from 'virtual:polen/project/assets/logo.svg'
 import PROJECT_DATA from 'virtual:polen/project/data.jsonsuper'
-import PROJECT_DATA_PAGES_CATALOG from 'virtual:polen/project/data/pages-catalog.jsonsuper'
-import { routes } from 'virtual:polen/project/routes.jsx'
+import PROJECT_SCHEMA from 'virtual:polen/project/schema.jsonsuper'
 import { templateVariables } from 'virtual:polen/template/variables'
-import { GraphQLSchemaProvider } from '../../lib/graphql-document/schema-context.js'
-import { CodeBlock } from '../components/CodeBlock.js'
-import { Pre } from '../components/CodeHikePre.js'
 import { Link as PolenLink } from '../components/Link.js'
 import { Logo } from '../components/Logo.js'
 import { NotFound } from '../components/NotFound.js'
@@ -40,22 +14,14 @@ import { ThemeToggle } from '../components/ThemeToggle.js'
 import { ThemeProvider, useTheme } from '../contexts/ThemeContext.js'
 import { changelog } from './changelog.js'
 import { index } from './index.js'
+import { pages } from './pages.js'
 import { reference } from './reference.js'
 
 export const Component = () => {
-  const schema = PROJECT_DATA.schema?.versions[0]?.after || null
-
-  // Make schema available globally for MDX components
-  if (typeof window !== `undefined` && schema) {
-    ;(window as any).__POLEN_GRAPHQL_SCHEMA__ = schema
-  }
-
   return (
     <>
       <ThemeProvider>
-        <GraphQLSchemaProvider schema={schema}>
-          <Layout />
-        </GraphQLSchemaProvider>
+        <Layout />
       </ThemeProvider>
       <ScrollRestoration />
     </>
@@ -105,82 +71,15 @@ const Layout = () => {
         py={{ initial: `4`, sm: `4`, md: `0` }}
       >
         {header}
-        <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} />,
-            pre: Pre,
-            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
-            CodeBlock,
-          }}
-        >
-          <Outlet />
-        </MDXProvider>
+        <Outlet />
       </Box>
     </Theme>
   )
 }
 
-const PagesLayout = () => {
-  const location = useLocation() // Add this line
-
-  // 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 (
-    <SidebarLayout sidebar={sidebar}>
-      <Outlet />
-    </SidebarLayout>
-  )
-}
-
 const children: ReactRouter.RouteObject[] = [
   index,
-  {
-    // Pathless layout route - doesn't affect URL paths
-    Component: PagesLayout,
-    children: [...routes], // All MDX page routes go here
-  },
+  pages,
 ]
 
 //
@@ -192,7 +91,7 @@ const children: ReactRouter.RouteObject[] = [
 //
 //
 
-if (PROJECT_DATA.schema) {
+if (PROJECT_SCHEMA) {
   children.push(changelog)
   children.push(reference)
 }

package/src/template/server/app.ts

@@ -1,7 +1,6 @@
 import { Hono } from '#dep/hono/index'
 import { createHtmlTransformer, type HtmlTransformer } from '#lib/html-utils/html-transformer'
 import { serveStatic } from '@hono/node-server/serve-static'
-import PROJECT_DATA from 'virtual:polen/project/data.jsonsuper'
 import viteClientAssetManifest from 'virtual:polen/vite/client/manifest'
 import { injectManifestIntoHtml } from './manifest.js'
 import { PageMiddleware } from './middleware/page.js'
@@ -9,16 +8,60 @@ import { UnsupportedAssetsMiddleware } from './middleware/unsupported-assets.js'
 import { createPolenDataInjector } from './transformers/inject-polen-data.js'
 import { createThemeInitInjector } from './transformers/inject-theme-init.js'
 
+export type App = Hono.Hono
+
 export interface AppHooks {
   transformHtml?: HtmlTransformer[]
 }
 
 export interface AppOptions {
   hooks?: AppHooks
+  paths: {
+    base: string
+    assets: {
+      /**
+       * Directory path for serving static assets.
+       * MUST be a relative path from process.cwd() due to @hono/node-server constraints.
+       * Absolute paths are NOT supported by the serveStatic middleware.
+       *
+       * @example './node_modules/.vite/polen-assets'
+       * @example '../../../polen/node_modules/.vite/polen-assets'
+       * @example './dist/assets'
+       */
+      directory: string
+      /**
+       * URL route prefix for serving assets
+       * @example '/assets'
+       */
+      route: string
+    }
+  }
 }
 
-export const createApp = (options: AppOptions = {}) => {
-  const app = new Hono.Hono()
+export const createApp = (options: AppOptions) => {
+  const app = new Hono.Hono().basePath(options.paths.base)
+
+  // Static file serving
+  app.use(`*`, UnsupportedAssetsMiddleware())
+
+  const assetsRoutePattern = `${options.paths.assets.route}/*`
+
+  app.use(
+    assetsRoutePattern,
+    serveStatic({
+      root: options.paths.assets.directory,
+      rewriteRequestPath: (path) => {
+        // When basePath is set, the full path including base is passed here
+        // We need to strip both the base path and the assets route
+        const basePath = options.paths.base === '/' ? '' : options.paths.base
+        const fullPrefix = `${basePath}${options.paths.assets.route}`
+        return path.replace(new RegExp(`^${fullPrefix}`), '')
+      },
+      onNotFound(path) {
+        console.log('not found', path)
+      },
+    }),
+  )
 
   // Collect all HTML transformers
   const htmlTransformers: HtmlTransformer[] = [
@@ -29,21 +72,11 @@ export const createApp = (options: AppOptions = {}) => {
     ...(options.hooks?.transformHtml || []),
   ]
 
-  // Core middleware
-  app.use(`*`, UnsupportedAssetsMiddleware())
-
-  // Production-specific setup
   if (__BUILDING__) {
     // Add manifest transformer
     htmlTransformers.push(createHtmlTransformer((html, ___ctx) => {
-      return injectManifestIntoHtml(html, viteClientAssetManifest, PROJECT_DATA.basePath)
+      return injectManifestIntoHtml(html, viteClientAssetManifest, options.paths.base)
     }))
-
-    // Static file serving
-    app.use(
-      PROJECT_DATA.server.static.route,
-      serveStatic({ root: PROJECT_DATA.server.static.directory }),
-    )
   }
 
   app.all(`*`, PageMiddleware(htmlTransformers))

package/src/template/server/main.ts

@@ -12,7 +12,15 @@ if (__BUILDING__) {
       break
     case `ssr`:
       const port = process.env[`PORT`] ? parseInt(process.env[`PORT`]) : PROJECT_DATA.server.port
-      const app = createApp()
+      const app = createApp({
+        paths: {
+          assets: {
+            directory: PROJECT_DATA.paths.project.relative.build.relative.assets.root,
+            route: PROJECT_DATA.server.routes.assets,
+          },
+          base: PROJECT_DATA.basePath,
+        },
+      })
       serve({ fetch: app.fetch, port })
       break
     case `spa`: