polen 0.10.0 → 0.11.0-next.10

package/src/template/routes/pages.tsx

@@ -0,0 +1,109 @@
+import { route } 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 = route({
+  // Pathless layout route - doesn't affect URL paths
+  loader,
+  Component,
+  children: [...routes], // All MDX page routes go here
+})

package/src/template/routes/reference.tsx

@@ -1,21 +1,35 @@
 import type { Content } from '#api/content/$'
 import { GrafaidOld } from '#lib/grafaid-old/index'
-import { createRoute } from '#lib/react-router-aid/react-router-aid'
+import { Grafaid } from '#lib/grafaid/index'
+import { route, routeIndex } from '#lib/react-router-aid/react-router-aid'
 import { createLoader, useLoaderData } from '#lib/react-router-loader/react-router-loader'
-import { Outlet } from 'react-router'
-import PROJECT_DATA from 'virtual:polen/project/data.jsonsuper'
+import { Box } from '@radix-ui/themes'
+import { Outlet, useParams } from 'react-router'
+import { Field } from '../components/Field.js'
 import { MissingSchema } from '../components/MissingSchema.js'
+import { NamedType } from '../components/NamedType.js'
+import { VersionSelector } from '../components/VersionSelector.js'
 import { SidebarLayout } from '../layouts/index.js'
-import { reference$type } from './reference.$type.js'
+import { VERSION_LATEST } from '../lib/schema-utils/constants.js'
+import { schemaSource } from '../sources/schema-source.js'
+
+export 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,
   }
 })
 
-const Component = () => {
+const RouteReferenceComponent = () => {
   const data = useLoaderData<typeof loader>()
 
   if (!data.schema) {
@@ -28,6 +42,12 @@ const Component = () => {
   const sidebarItems: Content.Item[] = []
   const kindEntries = Object.entries(kindMap.list).filter(([_, types]) => types.length > 0)
 
+  // Build path prefix based on current version from loader data
+  // This ensures sidebar links always match the current version being viewed
+  const versionPath = data.currentVersion === VERSION_LATEST
+    ? ``
+    : `version/${data.currentVersion}/`
+
   for (const [title, types] of kindEntries) {
     sidebarItems.push({
       type: `ItemSection` as const,
@@ -37,21 +57,101 @@ 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>
   )
 }
 
-export const reference = createRoute({
+// Shared hooks for schema data validation and retrieval
+const useReferenceSchema = () => {
+  const data = useLoaderData<typeof loader>('reference')
+  if (!data?.schema) {
+    throw new Error('Schema not found')
+  }
+  return data
+}
+
+const useSchemaType = (typeName: string) => {
+  const { schema } = useReferenceSchema()
+  const type = schema.getType(typeName)
+  if (!type) {
+    throw new Error(`Could not find type ${typeName}`)
+  }
+  return type
+}
+
+const useSchemaField = (typeName: string, fieldName: string) => {
+  const type = useSchemaType(typeName)
+  if (!Grafaid.Schema.TypesLike.isFielded(type)) {
+    throw new Error(`Type ${typeName} does not have fields`)
+  }
+
+  const fields = type.getFields()
+  const field = fields[fieldName]
+  if (!field) {
+    throw new Error(`Could not find field ${fieldName} on type ${typeName}`)
+  }
+  return field
+}
+
+const RouteComponentIndex = () => {
+  return <div>Select a type from the sidebar to view its documentation.</div>
+}
+
+const RouteComponentType = () => {
+  const params = useParams() as { type: string }
+  const type = useSchemaType(params.type)
+  return <NamedType data={type} />
+}
+
+const RouteComponentTypeField = () => {
+  const params = useParams() as { type: string; field: string }
+  const field = useSchemaField(params.type, params.field)
+  return <Field data={field} />
+}
+
+const typeAndFieldRoutes = [
+  routeIndex(RouteComponentIndex),
+  route({
+    path: `:type`,
+    Component: RouteComponentType,
+    errorElement: <MissingSchema />,
+    children: [
+      route({
+        path: `:field`,
+        Component: RouteComponentTypeField,
+        errorElement: <MissingSchema />,
+      }),
+    ],
+  }),
+]
+
+/**
+ * Reference documentation with proper nested structure - all routes in one file
+ */
+export const reference = route({
+  id: 'reference',
   path: `reference`,
   loader,
-  Component,
-  children: [reference$type],
+  Component: RouteReferenceComponent,
+  children: [
+    ...typeAndFieldRoutes,
+    route({
+      path: `version/:version`,
+      children: typeAndFieldRoutes,
+    }),
+  ],
 })

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 { route } from '#lib/react-router-aid/react-router-aid'
+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)
 }
@@ -206,7 +105,7 @@ if (PROJECT_DATA.schema) {
 //
 //
 
-const notFoundRoute = createRoute({
+const notFoundRoute = route({
   id: `*_not_found`,
   path: `*`,
   Component: NotFound,
@@ -223,7 +122,7 @@ children.push(notFoundRoute)
 //
 //
 
-export const root = createRoute({
+export const root = route({
   path: `/`,
   Component,
   children,

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`:

package/src/template/server/ssg/generate.ts

@@ -14,7 +14,7 @@ import { getRoutesPaths } from './get-route-paths.js'
 export const generate = async (view: ReactRouter.StaticHandler) => {
   const debug = debugPolen.sub(`ssg`)
 
-  const routePaths = getRoutesPaths()
+  const routePaths = await getRoutesPaths()
   const totalPaths = routePaths.length
   debug(`start`, { totalPaths })
 
@@ -76,7 +76,7 @@ export const generate = async (view: ReactRouter.StaticHandler) => {
 
       const ssgResult = await Hono.SSG.toSSG(batchApp, NodeFs, {
         concurrency: 5, // Reduced concurrency for memory efficiency
-        dir: PROJECT_DATA.paths.relative.build.root,
+        dir: PROJECT_DATA.paths.project.relative.build.root,
       })
 
       if (!ssgResult.success) {