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

package/src/template/components/sidebar/Sidebar.tsx

@@ -1,28 +1,32 @@
 import type { Content } from '#api/content/$'
 import { Box } from '@radix-ui/themes'
 import type { BoxOwnProps, LayoutProps, MarginProps } from '@radix-ui/themes/props'
+import { SidebarContext } from './SidebarContext.js'
 import { Items } from './SidebarItem.js'
 
-interface SidebarProps extends LayoutProps, MarginProps, BoxOwnProps {
+interface Props extends LayoutProps, MarginProps, BoxOwnProps {
   data: Content.Item[]
+  basePath?: string
   style?: React.CSSProperties
 }
 
-export const Sidebar = ({ data, ...props }: SidebarProps) => {
+export const Sidebar = ({ data, basePath, ...props }: Props) => {
   return (
-    <Box
-      data-testid='sidebar'
-      role='Sidebar'
-      {...props}
-    >
-      <style>
-        {`
-          div[role="Sidebar"] a:not([data-active]):hover {
-            background-color: var(--iris-2) !important;
-          }
-        `}
-      </style>
-      <Items items={data} />
-    </Box>
+    <SidebarContext.Provider value={{ basePath }}>
+      <Box
+        data-testid='sidebar'
+        role='Sidebar'
+        {...props}
+      >
+        <style>
+          {`
+            div[role="Sidebar"] a:not([data-active]):hover {
+              background-color: var(--iris-2) !important;
+            }
+          `}
+        </style>
+        <Items items={data} />
+      </Box>
+    </SidebarContext.Provider>
   )
 }

package/src/template/components/sidebar/SidebarContext.tsx

@@ -0,0 +1,7 @@
+import { createContext } from 'react'
+
+interface SidebarContextValue {
+  basePath?: string
+}
+
+export const SidebarContext = createContext<SidebarContextValue>({})

package/src/template/components/sidebar/SidebarItem.tsx

@@ -1,9 +1,12 @@
 import type { Content } from '#api/content/$'
+import { Api } from '#api/iso'
 import type { React } from '#dep/react/index'
 import { Texts } from '#template/components/Texts/index'
 import { Box, Flex } from '@radix-ui/themes'
+import { useContext } from 'react'
 import { useLocation } from 'react-router'
 import { getPathActiveReport, Link } from '../Link.js'
+import { SidebarContext } from './SidebarContext.js'
 
 export const Items: React.FC<{ items: Content.Item[] }> = ({ items }) => {
   return (
@@ -50,15 +53,17 @@ const SBLink: React.FC<{
   link: Content.ItemLink | Content.ItemSection
 }> = ({ link }) => {
   const location = useLocation()
+  const { basePath } = useContext(SidebarContext)
   const currentPathExp = location.pathname
-  const active = getPathActiveReport(link.pathExp, currentPathExp)
+  const href = Api.Schema.Routing.joinSegmentsAndPaths(basePath, link.pathExp)
+  const active = getPathActiveReport(href, currentPathExp)
 
   return (
     <Link
       role='Sidebar Link'
       color={active.is ? `iris` : `gray`}
       data-testid={`sidebar-link-${link.pathExp}`}
-      to={`/${link.pathExp}`}
+      to={href}
       style={{
         display: `block`,
         textDecoration: `none`,
@@ -135,12 +140,14 @@ const LinkedSection: React.FC<{
 
 const SectionLink: React.FC<{ link: Content.ItemLink }> = ({ link }) => {
   const location = useLocation()
-  const active = getPathActiveReport(link.pathExp, location.pathname)
+  const { basePath } = useContext(SidebarContext)
+  const href = Api.Schema.Routing.joinSegmentsAndPaths(basePath, link.pathExp)
+  const active = getPathActiveReport(href, location.pathname)
 
   return (
     <Link
       role='Sidebar Link'
-      to={`/` + link.pathExp}
+      to={href}
       color={active.is ? `iris` : `gray`}
       style={{
         textDecoration: `none`,

package/src/template/hooks/useVersionPath.ts

@@ -1,3 +1,4 @@
+import { Api } from '#api/iso'
 import { useParams } from 'react-router'
 
 /**
@@ -6,5 +7,6 @@ import { useParams } from 'react-router'
  */
 export const useVersionPath = (): string => {
   const params = useParams()
-  return params[`version`] ? `version/${params[`version`]}/` : ``
+  const version = params[`version`] || Api.Schema.VERSION_LATEST
+  return Api.Schema.Routing.createReferenceVersionPath(version)
 }

package/src/template/layouts/SidebarLayout.tsx

@@ -6,12 +6,13 @@ import { useLocation } from 'react-router'
 import { HamburgerMenu } from '../components/HamburgerMenu.js'
 import { Sidebar } from '../components/sidebar/Sidebar.js'
 
-interface SidebarLayoutProps {
+interface Props {
   children: React.ReactNode
   sidebar: Content.Item[]
+  basePath?: string
 }
 
-export const SidebarLayout: React.FC<SidebarLayoutProps> = ({ children, sidebar }) => {
+export const SidebarLayout: React.FC<Props> = ({ children, sidebar, basePath }) => {
   const location = useLocation()
   const [mobileMenuOpen, setMobileMenuOpen] = useState(false)
 
@@ -45,6 +46,7 @@ export const SidebarLayout: React.FC<SidebarLayoutProps> = ({ children, sidebar
               setMobileMenuOpen(false)
             }}
             sidebarData={sidebar}
+            basePath={basePath}
           />
         </Box>
       )}
@@ -56,7 +58,7 @@ export const SidebarLayout: React.FC<SidebarLayoutProps> = ({ children, sidebar
           gridColumn='1 / 3'
           gridRow='1 / auto'
         >
-          <Sidebar data={sidebar} />
+          <Sidebar data={sidebar} basePath={basePath} />
         </Box>
       )}
 

package/src/template/routes/changelog.tsx

@@ -1,5 +1,5 @@
 import type { GraphqlChangeset } from '#lib/graphql-changeset/index'
-import { createRoute } from '#lib/react-router-aid/react-router-aid'
+import { route } from '#lib/react-router-aid/react-router-aid'
 import { createLoader, useLoaderData } from '#lib/react-router-loader/react-router-loader'
 import { Changelog } from '../components/Changelog.js'
 import { ChangelogLayout } from '../layouts/index.js'
@@ -33,7 +33,7 @@ const Component = () => {
   )
 }
 
-export const changelog = createRoute({
+export const changelog = route({
   path: `changelog`,
   loader,
   Component,

package/src/template/routes/index.tsx

@@ -1,10 +1,10 @@
-import { createRouteIndex } from '#lib/react-router-aid/react-router-aid'
+import { routeIndex } from '#lib/react-router-aid/react-router-aid'
 import { Box } from '@radix-ui/themes'
 
 const Component = () => {
   return <Box>home todo</Box>
 }
 
-export const index = createRouteIndex({
+export const index = routeIndex({
   Component,
 })

package/src/template/routes/pages.tsx

@@ -1,4 +1,4 @@
-import { createRoute } from '#lib/react-router-aid/react-router-aid'
+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'
@@ -101,7 +101,7 @@ const Component = () => {
   )
 }
 
-export const pages = createRoute({
+export const pages = route({
   // Pathless layout route - doesn't affect URL paths
   loader,
   Component,

package/src/template/routes/reference.tsx

@@ -1,23 +1,23 @@
 import type { Content } from '#api/content/$'
+import { Api } from '#api/iso'
 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 { Box } from '@radix-ui/themes'
-import { Outlet } from 'react-router'
+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 { 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 }) => {
+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 currentVersion = params.version ?? Api.Schema.VERSION_LATEST
 
   const schema = await schemaSource.get(currentVersion)
   const availableVersions = schemaSource.versions
@@ -29,7 +29,7 @@ const loader = createLoader(async ({ params }) => {
   }
 })
 
-const Component = () => {
+const RouteReferenceComponent = () => {
   const data = useLoaderData<typeof loader>()
 
   if (!data.schema) {
@@ -42,9 +42,6 @@ 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,
@@ -54,13 +51,16 @@ const Component = () => {
       links: types.map(type => ({
         type: `ItemLink` as const,
         title: type.name,
-        pathExp: `reference/${versionPath}${type.name}`,
+        pathExp: type.name, // Just the type name, basePath will be prepended
       })),
     })
   }
 
+  // Calculate basePath based on current version
+  const basePath = Api.Schema.Routing.createReferenceBasePath(data.currentVersion)
+
   return (
-    <SidebarLayout sidebar={sidebarItems}>
+    <SidebarLayout sidebar={sidebarItems} basePath={basePath}>
       <Box mb={`4`}>
         <VersionSelector
           availableVersions={data.availableVersions}
@@ -72,18 +72,83 @@ const Component = () => {
   )
 }
 
-// Create the versioned reference route with explicit version prefix
-const referenceVersioned = createRoute({
-  path: `version/:version`,
-  loader,
-  Component,
-  children: [referenceVersion$version$type],
-})
+// 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 />,
+      }),
+    ],
+  }),
+]
 
-// Create the main reference route with explicit version path and fallback type path
-export const reference = createRoute({
+/**
+ * Reference documentation with proper nested structure - all routes in one file
+ */
+export const reference = route({
+  id: 'reference',
   path: `reference`,
   loader,
-  Component,
-  children: [referenceVersioned, reference$type],
+  Component: RouteReferenceComponent,
+  children: [
+    ...typeAndFieldRoutes,
+    route({
+      path: `version/:version`,
+      children: typeAndFieldRoutes,
+    }),
+  ],
 })

package/src/template/routes/root.tsx

@@ -1,5 +1,5 @@
 import type { ReactRouter } from '#dep/react-router/index'
-import { createRoute } from '#lib/react-router-aid/react-router-aid'
+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'
@@ -105,7 +105,7 @@ if (PROJECT_SCHEMA) {
 //
 //
 
-const notFoundRoute = createRoute({
+const notFoundRoute = route({
   id: `*_not_found`,
   path: `*`,
   Component: NotFound,
@@ -122,7 +122,7 @@ children.push(notFoundRoute)
 //
 //
 
-export const root = createRoute({
+export const root = route({
   path: `/`,
   Component,
   children,

package/src/template/server/ssg/get-route-paths.test.ts

@@ -0,0 +1,145 @@
+import { beforeEach, describe, expect, test, vi } from 'vitest'
+
+// Mock node:fs/promises
+vi.mock('node:fs/promises', () => ({
+  readFile: vi.fn(),
+}))
+
+// Mock the virtual import
+vi.mock('virtual:polen/project/data.jsonsuper', () => ({
+  default: {
+    paths: {
+      project: {
+        absolute: {
+          build: {
+            assets: {
+              schemas: '/mock/schemas',
+            },
+          },
+        },
+      },
+    },
+  },
+}))
+
+// Mock the routes
+vi.mock('../../routes.js', () => ({
+  routes: [
+    {
+      path: 'reference',
+      children: [
+        {
+          path: 'version/:version',
+          children: [
+            {
+              path: ':type',
+            },
+          ],
+        },
+        {
+          path: ':type',
+        },
+      ],
+    },
+  ],
+}))
+
+// Mock the API
+vi.mock('#api/index', () => ({
+  Api: {
+    Schema: {
+      getMetadata: vi.fn(),
+      VERSION_LATEST: 'latest',
+      Routing: {
+        createReferencePath: vi.fn((parts) => {
+          const version = parts.version || 'latest'
+          const basePath = version === 'latest' ? '/reference' : `/reference/version/${version}`
+          if (parts.type) {
+            return parts.field ? `${basePath}/${parts.type}/${parts.field}` : `${basePath}/${parts.type}`
+          }
+          return basePath
+        }),
+        createReferenceBasePath: vi.fn((version) => {
+          return version === 'latest' ? '/reference' : `/reference/version/${version}`
+        }),
+      },
+    },
+  },
+}))
+
+describe('getRoutesPaths', () => {
+  beforeEach(() => {
+    vi.resetAllMocks()
+  })
+
+  test('should handle versioned routes without type parameter', async () => {
+    // Mock schema metadata
+    const { Api } = await import('#api/index')
+    vi.mocked(Api.Schema.getMetadata).mockResolvedValue({
+      hasSchema: true,
+      versions: ['2024-01-01', '2024-02-01'],
+    })
+
+    // Mock file system reads with proper GraphQL AST
+    const NodeFs = await import('node:fs/promises')
+    vi.mocked(NodeFs.readFile).mockImplementation(async (path) => {
+      if (typeof path === 'string' && path.includes('.json')) {
+        // Return a minimal GraphQL document AST
+        return JSON.stringify({
+          kind: 'Document',
+          definitions: [],
+        })
+      }
+      throw new Error(`Unexpected file read: ${path}`)
+    })
+
+    const { getRoutesPaths } = await import('./get-route-paths.js')
+
+    // This should not throw "Unhandled parameterized path: /reference/version/:version"
+    await expect(getRoutesPaths()).resolves.toBeDefined()
+  })
+
+  test('should generate paths for all schema versions', async () => {
+    const { Api } = await import('#api/index')
+    vi.mocked(Api.Schema.getMetadata).mockResolvedValue({
+      hasSchema: true,
+      versions: ['2024-01-01', '2024-02-01'],
+    })
+
+    // Mock schema with types - proper GraphQL AST
+    const mockSchema = {
+      kind: 'Document',
+      definitions: [
+        {
+          kind: 'ObjectTypeDefinition',
+          name: { kind: 'Name', value: 'User' },
+        },
+        {
+          kind: 'ObjectTypeDefinition',
+          name: { kind: 'Name', value: 'Post' },
+        },
+      ],
+    }
+
+    const NodeFs = await import('node:fs/promises')
+    vi.mocked(NodeFs.readFile).mockImplementation(async (path) => {
+      if (typeof path === 'string' && path.includes('.json')) {
+        return JSON.stringify(mockSchema)
+      }
+      throw new Error(`Unexpected file read: ${path}`)
+    })
+
+    const { getRoutesPaths } = await import('./get-route-paths.js')
+    const paths = await getRoutesPaths()
+
+    // Should include versioned paths
+    expect(paths).toContain('/reference/version/2024-01-01/User')
+    expect(paths).toContain('/reference/version/2024-01-01/Post')
+    expect(paths).toContain('/reference/version/2024-02-01/User')
+    expect(paths).toContain('/reference/version/2024-02-01/Post')
+
+    // Should include unversioned paths
+    expect(paths).toContain('/reference/User')
+    expect(paths).toContain('/reference/Post')
+  })
+})

package/src/template/server/ssg/get-route-paths.ts

@@ -11,7 +11,10 @@ import { routes } from '../../routes.js'
 // Maybe we can figure something out too.
 const knownParameterizedRouteExpressions = {
   reference_type: `/reference/:type`,
+  reference_type_field: `/reference/:type/:field`,
+  reference_version: `/reference/version/:version`,
   reference_versioned_type: `/reference/version/:version/:type`,
+  reference_versioned_type_field: `/reference/version/:version/:type/:field`,
 }
 
 export const getRoutesPaths = async (): Promise<string[]> => {
@@ -19,7 +22,7 @@ export const getRoutesPaths = async (): Promise<string[]> => {
   const routeExpressions = ReactRouterAid.getRouteExpressions(routes)
 
   // Helper function to load schema from filesystem and add type paths
-  const addTypePathsForVersion = async (version: string, pathPrefix: string) => {
+  const addTypePathsForVersion = async (version: string, includeFields = false) => {
     try {
       const schemaFilePath = NodePath.join(PROJECT_DATA.paths.project.absolute.build.assets.schemas, `${version}.json`)
       const schemaContent = await NodeFs.readFile(schemaFilePath, 'utf-8')
@@ -27,22 +30,70 @@ export const getRoutesPaths = async (): Promise<string[]> => {
 
       visit(schemaAst, {
         ObjectTypeDefinition(node) {
-          paths.add(`${pathPrefix}/${node.name.value}`)
+          const typePath = Api.Schema.Routing.createReferencePath({
+            version: version === Api.Schema.VERSION_LATEST ? undefined : version,
+            type: node.name.value,
+          })
+          paths.add(typePath)
+
+          // Add field paths if requested
+          if (includeFields && node.fields) {
+            for (const field of node.fields) {
+              const fieldPath = Api.Schema.Routing.createReferencePath({
+                version: version === Api.Schema.VERSION_LATEST ? undefined : version,
+                type: node.name.value,
+                field: field.name.value,
+              })
+              paths.add(fieldPath)
+            }
+          }
         },
         InterfaceTypeDefinition(node) {
-          paths.add(`${pathPrefix}/${node.name.value}`)
+          const typePath = Api.Schema.Routing.createReferencePath({
+            version: version === Api.Schema.VERSION_LATEST ? undefined : version,
+            type: node.name.value,
+          })
+          paths.add(typePath)
+
+          // Add field paths if requested
+          if (includeFields && node.fields) {
+            for (const field of node.fields) {
+              const fieldPath = Api.Schema.Routing.createReferencePath({
+                version: version === Api.Schema.VERSION_LATEST ? undefined : version,
+                type: node.name.value,
+                field: field.name.value,
+              })
+              paths.add(fieldPath)
+            }
+          }
         },
         EnumTypeDefinition(node) {
-          paths.add(`${pathPrefix}/${node.name.value}`)
+          const typePath = Api.Schema.Routing.createReferencePath({
+            version: version === Api.Schema.VERSION_LATEST ? undefined : version,
+            type: node.name.value,
+          })
+          paths.add(typePath)
         },
         InputObjectTypeDefinition(node) {
-          paths.add(`${pathPrefix}/${node.name.value}`)
+          const typePath = Api.Schema.Routing.createReferencePath({
+            version: version === Api.Schema.VERSION_LATEST ? undefined : version,
+            type: node.name.value,
+          })
+          paths.add(typePath)
         },
         UnionTypeDefinition(node) {
-          paths.add(`${pathPrefix}/${node.name.value}`)
+          const typePath = Api.Schema.Routing.createReferencePath({
+            version: version === Api.Schema.VERSION_LATEST ? undefined : version,
+            type: node.name.value,
+          })
+          paths.add(typePath)
         },
         ScalarTypeDefinition(node) {
-          paths.add(`${pathPrefix}/${node.name.value}`)
+          const typePath = Api.Schema.Routing.createReferencePath({
+            version: version === Api.Schema.VERSION_LATEST ? undefined : version,
+            type: node.name.value,
+          })
+          paths.add(typePath)
         },
       })
     } catch (error) {
@@ -59,13 +110,33 @@ export const getRoutesPaths = async (): Promise<string[]> => {
     if (exp === knownParameterizedRouteExpressions.reference_type) {
       if (hasSchema) {
         // Add paths for latest version (no version in URL)
-        await addTypePathsForVersion(Api.Schema.VERSION_LATEST, `/reference`)
+        await addTypePathsForVersion(Api.Schema.VERSION_LATEST)
+      }
+    } else if (exp === knownParameterizedRouteExpressions.reference_version) {
+      if (hasSchema) {
+        // Add paths for version pages themselves (without type)
+        for (const version of availableVersions) {
+          const versionPath = Api.Schema.Routing.createReferenceBasePath(version)
+          paths.add(versionPath)
+        }
+      }
+    } else if (exp === knownParameterizedRouteExpressions.reference_type_field) {
+      if (hasSchema) {
+        // Add paths for latest version fields
+        await addTypePathsForVersion(Api.Schema.VERSION_LATEST, true)
       }
     } else if (exp === knownParameterizedRouteExpressions.reference_versioned_type) {
       if (hasSchema) {
         // Add paths for all versions using new route structure
         for (const version of availableVersions) {
-          await addTypePathsForVersion(version, `/reference/version/${version}`)
+          await addTypePathsForVersion(version)
+        }
+      }
+    } else if (exp === knownParameterizedRouteExpressions.reference_versioned_type_field) {
+      if (hasSchema) {
+        // Add paths for all versions with fields
+        for (const version of availableVersions) {
+          await addTypePathsForVersion(version, true)
         }
       }
     } else if (ReactRouterAid.isParameterizedPath(exp)) {

package/src/template/sources/schema-source.ts

@@ -13,8 +13,9 @@ const io = import.meta.env.SSR
 
       // Extract the path after the assets route
       // e.g., "/assets/schemas/latest.json" -> "schemas/latest.json"
+      // e.g., "/demos/pokemon/assets/schemas/latest.json" -> "schemas/latest.json"
       const assetsRoute = PROJECT_DATA.server.routes.assets
-      const routePattern = new RegExp(`^${assetsRoute}/(.+)$`)
+      const routePattern = new RegExp(`${assetsRoute}/(.+)$`)
       const match = path.match(routePattern)
       const assetPath = match ? match[1] : path