polen 0.10.0-next.9 → 0.11.0-next.1

package/src/template/layouts/ChangelogLayout.tsx

@@ -0,0 +1,157 @@
+import {
+  CRITICALITY_CONFIG,
+  isCriticalityBreaking,
+  isCriticalityDangerous,
+  isCriticalitySafe,
+} from '#lib/graphql-change/criticality'
+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 '../components/Changelog.js'
+
+interface ChangelogLayoutProps {
+  children: React.ReactNode
+  versions: GraphqlChangeset.ChangeSet[]
+}
+
+interface VersionCounts {
+  breaking: number
+  dangerous: number
+  safe: number
+}
+
+const calculateCounts = (version: GraphqlChangeset.ChangeSet): VersionCounts => {
+  return {
+    breaking: version.changes.filter(isCriticalityBreaking).length,
+    dangerous: version.changes.filter(isCriticalityDangerous).length,
+    safe: version.changes.filter(isCriticalitySafe).length,
+  }
+}
+
+const SidebarEntry: React.FC<{
+  version: GraphqlChangeset.ChangeSet
+  counts: VersionCounts
+  isActive: boolean
+}> = ({ version, counts, isActive }) => {
+  const dateId = version.date.toISOString()
+
+  return (
+    <Box mb='2'>
+      <a
+        href={`#${dateId}`}
+        style={{
+          textDecoration: 'none',
+          display: 'flex',
+          alignItems: 'center',
+          justifyContent: 'space-between',
+          padding: '0.5rem 0.75rem',
+          borderRadius: '4px',
+          backgroundColor: isActive ? 'var(--gray-a3)' : 'transparent',
+          color: 'inherit',
+          transition: 'background-color 0.2s',
+        }}
+        onClick={(e) => {
+          e.preventDefault()
+          document.getElementById(dateId)?.scrollIntoView({ behavior: 'smooth' })
+        }}
+      >
+        <Text size='2' weight={isActive ? 'medium' : 'regular'}>
+          {renderDate(version.date)}
+        </Text>
+        <Flex gap='2' align='center'>
+          {counts.breaking > 0 && (
+            <Text size='1' weight='medium' style={{ color: CRITICALITY_CONFIG.BREAKING.color }}>
+              {counts.breaking}
+            </Text>
+          )}
+          {counts.dangerous > 0 && (
+            <Text size='1' weight='medium' style={{ color: CRITICALITY_CONFIG.DANGEROUS.color }}>
+              {counts.dangerous}
+            </Text>
+          )}
+          {counts.safe > 0 && (
+            <Text size='1' weight='medium' style={{ color: CRITICALITY_CONFIG.NON_BREAKING.color }}>
+              {counts.safe}
+            </Text>
+          )}
+        </Flex>
+      </a>
+    </Box>
+  )
+}
+
+export const ChangelogLayout: React.FC<ChangelogLayoutProps> = ({ children, versions }) => {
+  const [activeVersion, setActiveVersion] = useState<string | null>(null)
+
+  // Calculate counts for all versions (SSR-safe)
+  const versionsWithCounts = versions.map(version => ({
+    version,
+    counts: calculateCounts(version),
+  }))
+
+  // Set up scroll spy after hydration
+  useEffect(() => {
+    const handleScroll = () => {
+      const scrollPosition = window.scrollY + 100 // Offset for header
+
+      // Find the current version based on scroll position
+      let currentVersion: string | null = null
+
+      for (const { version } of versionsWithCounts) {
+        const element = document.getElementById(version.date.toISOString())
+        if (element) {
+          const { top } = element.getBoundingClientRect()
+          if (top <= 100) {
+            currentVersion = version.date.toISOString()
+          }
+        }
+      }
+
+      setActiveVersion(currentVersion)
+    }
+
+    // Initial check
+    handleScroll()
+
+    // Add scroll listener
+    window.addEventListener('scroll', handleScroll, { passive: true })
+
+    return () => {
+      window.removeEventListener('scroll', handleScroll)
+    }
+  }, [versionsWithCounts])
+
+  return (
+    <Flex gap='6' style={{ position: 'relative' }}>
+      {/* Sidebar */}
+      <Box
+        style={{
+          position: 'sticky',
+          top: '2rem',
+          height: 'fit-content',
+          minWidth: '250px',
+          maxHeight: 'calc(100vh - 4rem)',
+          overflowY: 'auto',
+        }}
+      >
+        <Text size='2' weight='medium' mb='3' style={{ display: 'block' }}>
+          Releases
+        </Text>
+        {versionsWithCounts.map(({ version, counts }) => (
+          <SidebarEntry
+            key={version.date.toISOString()}
+            version={version}
+            counts={counts}
+            isActive={activeVersion === version.date.toISOString()}
+          />
+        ))}
+      </Box>
+
+      {/* Main content */}
+      <Box style={{ flex: 1, minWidth: 0 }}>
+        {children}
+      </Box>
+    </Flex>
+  )
+}

package/src/template/layouts/SidebarLayout.tsx

@@ -0,0 +1,68 @@
+import type { Content } from '#api/content/$'
+import { Box, Grid } from '@radix-ui/themes'
+import type React from 'react'
+import { useEffect, useState } from 'react'
+import { useLocation } from 'react-router'
+import { HamburgerMenu } from '../components/HamburgerMenu.js'
+import { Sidebar } from '../components/sidebar/Sidebar.js'
+
+interface SidebarLayoutProps {
+  children: React.ReactNode
+  sidebar: Content.Item[]
+}
+
+export const SidebarLayout: React.FC<SidebarLayoutProps> = ({ children, sidebar }) => {
+  const location = useLocation()
+  const [mobileMenuOpen, setMobileMenuOpen] = useState(false)
+
+  // Close mobile menu on route change
+  useEffect(() => {
+    setMobileMenuOpen(false)
+  }, [location.pathname])
+
+  const isShowSidebar = sidebar && sidebar.length > 0
+
+  return (
+    <Grid
+      areas={{
+        initial: `'content'`,
+        sm: `'content'`,
+        md: `'sidebar sidebar . content content content content content'`,
+      }}
+      rows='auto'
+      columns={{ initial: `1fr`, sm: `1fr`, md: `repeat(8, 1fr)` }}
+      gapX={{ initial: `0`, sm: `0`, md: `2` }}
+    >
+      {/* Mobile menu - only show when sidebar exists */}
+      {isShowSidebar && (
+        <Box display={{ initial: `block`, md: `none` }} mb='4'>
+          <HamburgerMenu
+            isOpen={mobileMenuOpen}
+            onToggle={() => {
+              setMobileMenuOpen(!mobileMenuOpen)
+            }}
+            onClose={() => {
+              setMobileMenuOpen(false)
+            }}
+            sidebarData={sidebar}
+          />
+        </Box>
+      )}
+
+      {/* Desktop Sidebar */}
+      {isShowSidebar && (
+        <Box
+          display={{ initial: `none`, xs: `none`, sm: `none`, md: `block` }}
+          gridColumn='1 / 3'
+          gridRow='1 / auto'
+        >
+          <Sidebar data={sidebar} />
+        </Box>
+      )}
+
+      <Box gridArea='content / content / auto / 8'>
+        {children}
+      </Box>
+    </Grid>
+  )
+}

package/src/template/layouts/index.ts

@@ -0,0 +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

@@ -0,0 +1,55 @@
+import PROJECT_DATA from 'virtual:polen/project/data.jsonsuper'
+
+/**
+ * Create a Polen URL path that respects the configured base path for UI navigation.
+ *
+ * **Warning:** When using this with raw `<a>` tags instead of React Router's Link component,
+ * you lose the following benefits:
+ * - Client-side navigation (faster, no page refresh)
+ * - Browser history management and back/forward optimization
+ * - Scroll position restoration
+ * - Route preloading and prefetching
+ * - Consistent navigation state management
+ * - Better accessibility features (screen reader announcements)
+ *
+ * Consider using React Router's `Link` component with `to={polenUrlPath(...)}` for better UX.
+ *
+ * @param segments - Path segments to join (e.g., 'reference', 'Pokemon')
+ * @returns Full URL path with base path (e.g., '/demos/pokemon/reference/Pokemon')
+ *
+ * @example
+ * polenUrlPath('reference', 'Pokemon') // '/demos/pokemon/reference/Pokemon'
+ * polenUrlPath('/reference/Pokemon') // '/demos/pokemon/reference/Pokemon'
+ * polenUrlPath('reference/Pokemon#field') // '/demos/pokemon/reference/Pokemon#field'
+ */
+export const polenUrlPath = (...segments: string[]): string => {
+  const basePath = PROJECT_DATA.basePath // e.g., '/demos/pokemon/'
+
+  // Join segments and normalize slashes
+  const path = segments
+    .join('/')
+    .replace(/\/+/g, '/') // Remove duplicate slashes
+    .replace(/^\//, '') // Remove leading slash
+
+  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,22 +1,36 @@
+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.jsx'
+import { Changelog } from '../components/Changelog.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 <Changelog schema={data.schema} />
+  return (
+    <ChangelogLayout versions={data.changesets}>
+      <Changelog changesets={data.changesets as [GraphqlChangeset.ChangeSet, ...GraphqlChangeset.ChangeSet[]]} />
+    </ChangelogLayout>
+  )
 }
 
 export const changelog = createRoute({

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

@@ -2,9 +2,9 @@ import { Grafaid } from '#lib/grafaid/index'
 import { ReactRouterAid } from '#lib/react-router-aid/index'
 import { useLoaderData } from '#lib/react-router-loader/react-router-loader'
 import { useParams } from 'react-router'
-import { Field } from '../components/Field.jsx'
-import { MissingSchema } from '../components/MissingSchema.jsx'
-import type { reference } from './reference.jsx'
+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 }
@@ -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

@@ -1,9 +1,10 @@
 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.jsx'
-import { NamedType } from '../components/NamedType.jsx'
-import type { reference } from './reference.jsx'
+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 = () => {
   const params = useParams() as { type: string }
@@ -24,4 +25,5 @@ const Component = () => {
 export const reference$type = createRoute({
   path: `:type`,
   Component,
+  children: [reference$type$field],
 })

package/src/template/routes/reference.tsx

@@ -1,16 +1,31 @@
+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 { Container, Flex } from '@radix-ui/themes'
+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.jsx'
-import { TypeIndex } from '../components/TypeIndex.jsx'
-import { reference$type } from './reference.$type.jsx'
+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,
   }
 })
 
@@ -21,19 +36,54 @@ const Component = () => {
     return <MissingSchema />
   }
 
+  // Build reference sidebar from schema types
+  const kindMap = GrafaidOld.getKindMap(data.schema)
+
+  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,
+      title,
+      pathExp: `reference-${title.toLowerCase()}`,
+      isLinkToo: false,
+      links: types.map(type => ({
+        type: `ItemLink` as const,
+        title: type.name,
+        pathExp: `reference/${versionPath}${type.name}`,
+      })),
+    })
+  }
+
   return (
-    <Flex direction='row' align='start'>
-      <TypeIndex schema={data.schema} />
-      <Container>
-        <Outlet />
-      </Container>
-    </Flex>
+    <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,
+})