polen 0.11.0-next.13 → 0.11.0-next.15

package/src/template/components/VersionPicker.tsx

@@ -1,44 +1,64 @@
 import { Api } from '#api/iso'
 import type { React } from '#dep/react/index'
+import { Version } from '#lib/version/$'
 import { Select } from '@radix-ui/themes'
+import { Effect } from 'effect'
 import { useNavigate } from 'react-router'
+import { catalogBridge } from '../catalog-bridge.js'
 import { useReferencePath } from '../hooks/useReferencePath.js'
-import { schemaSource } from '../sources/schema-source.js'
 import { Stores } from '../stores/$.js'
 import { tryWithToast } from '../utils/try-with-toast.js'
 
 interface Props {
-  all: string[]
-  current: string
+  data: readonly Version.Version[]
+  current: Version.Version
 }
 
-export const VersionPicker: React.FC<Props> = ({ all, current }) => {
+export const VersionPicker: React.FC<Props> = ({ data, current }) => {
   const navigate = useNavigate()
   const currentPath = useReferencePath()
 
   // Don't show selector if only one version
-  if (all.length <= 1) {
+  if (data.length <= 1) {
     return null
   }
 
   const handleVersionChange = async (newVersion: string) => {
     const error = await tryWithToast(async () => {
-      // Check if current path exists in target version
-      const targetSchema = await schemaSource.get(newVersion)
+      // Get the full catalog to find the target schema
+      const catalog = await Effect.runPromise(catalogBridge.view())
+
+      if (!catalog) {
+        throw new Error('No catalog available')
+      }
+
+      // This component is only used for versioned catalogs
+      if (catalog._tag !== 'CatalogVersioned') {
+        throw new Error('VersionPicker used with non-versioned catalog')
+      }
+
+      // Find the schema for the target version
+      // Note: newVersion is a string that we need to parse
+      const targetSchema = catalog.entries.find(schema => Version.toString(schema.version) === newVersion)
+
+      if (!targetSchema) {
+        throw new Error(`Version ${newVersion} not found`)
+      }
+
       // Find fallback path if needed
-      const fallbackPath = Api.Schema.Validation.findFallbackPath(targetSchema, currentPath)
+      const fallbackPath = Api.Schema.Validation.findFallbackPath(targetSchema.definition, currentPath)
       // Get redirect description if path changed
       const redirectDescription = Api.Schema.Validation.getRedirectDescription(
-        targetSchema,
+        targetSchema.definition,
         currentPath,
         fallbackPath,
         newVersion,
       )
-      // Create the new path
+      // Create the new path - parse newVersion string to Version type
       const newPath = Api.Schema.Routing.createReferencePath({
-        version: newVersion,
-        type: fallbackPath.type,
-        field: fallbackPath.field,
+        version: Version.fromString(newVersion),
+        type: fallbackPath.type || '',
+        field: fallbackPath.field || '',
       })
       // Show toast notification if schema location redirect will occur
       if (redirectDescription) {
@@ -69,25 +89,30 @@ export const VersionPicker: React.FC<Props> = ({ all, current }) => {
     if (error) {
       // Fallback to simple navigation if schema loading fails
       const newPath = Api.Schema.Routing.createReferencePath({
-        version: newVersion,
-        type: currentPath.type,
-        field: currentPath.field,
+        version: Version.fromString(newVersion),
+        type: currentPath.type || '',
+        field: currentPath.field || '',
       })
       navigate(newPath)
     }
   }
 
+  const currentStr = Version.toString(current)
+
   return (
-    <Select.Root value={current} onValueChange={handleVersionChange}>
+    <Select.Root value={currentStr} onValueChange={handleVersionChange}>
       <Select.Trigger>
-        {current === Api.Schema.VERSION_LATEST ? `Latest` : current}
+        {currentStr}
       </Select.Trigger>
       <Select.Content>
-        {all.map(version => (
-          <Select.Item key={version} value={version}>
-            {version === Api.Schema.VERSION_LATEST ? `Latest` : version}
-          </Select.Item>
-        ))}
+        {data.map(version => {
+          const versionStr = Version.toString(version)
+          return (
+            <Select.Item key={versionStr} value={versionStr}>
+              {versionStr}
+            </Select.Item>
+          )
+        })}
       </Select.Content>
     </Select.Root>
   )

package/src/template/components/navbar/DefaultNavbar.tsx

@@ -0,0 +1,22 @@
+import type { NavbarProps } from '#api/hooks/types'
+import { Flex } from '@radix-ui/themes'
+import type React from 'react'
+
+export const DefaultNavbar: React.FC<NavbarProps> = ({ items, Item, Logo, ThemeToggle }) => {
+  return (
+    <>
+      <Logo />
+      <Flex direction='row' gap='4' style={{ flex: 1 }}>
+        {items
+          .filter(item => item.position !== 'right')
+          .map((item, index) => <Item key={index} item={item} index={index} />)}
+      </Flex>
+      <Flex direction='row' gap='4'>
+        {items
+          .filter(item => item.position === 'right')
+          .map((item, index) => <Item key={index} item={item} index={index} />)}
+      </Flex>
+      <ThemeToggle />
+    </>
+  )
+}

package/src/template/components/navbar/Item.tsx

@@ -0,0 +1,11 @@
+import type { NavbarItem } from '#api/content/navbar'
+import type React from 'react'
+import { Link as PolenLink } from '../Link.js'
+
+export const Item: React.FC<{ item: NavbarItem; index: number }> = ({ item }) => {
+  return (
+    <PolenLink color='gray' to={item.pathExp}>
+      {item.title}
+    </PolenLink>
+  )
+}

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

@@ -13,7 +13,7 @@ interface Props extends LayoutProps, MarginProps, BoxOwnProps {
 
 export const Sidebar = ({ data, basePath, topContent, ...props }: Props) => {
   return (
-    <SidebarContext.Provider value={{ basePath }}>
+    <SidebarContext.Provider value={basePath !== undefined ? { basePath } : {}}>
       <Box
         data-testid='sidebar'
         role='Sidebar'

package/src/template/contexts/GraphqlLifecycleContext.tsx

@@ -0,0 +1,43 @@
+import type { React } from '#dep/react/index'
+import { Lifecycles } from '#lib/lifecycles/$'
+import { Schema } from '#lib/schema/$'
+import { createContext, useContext } from 'react'
+
+interface SchemaContextValue {
+  schema: Schema.Schema
+  lifecycles: Lifecycles.Lifecycles
+}
+
+const SchemaContext = createContext<SchemaContextValue | undefined>(undefined)
+
+export const GraphqlLifecycleProvider: React.FC<{
+  children: React.ReactNode
+  lifecycle: Lifecycles.Lifecycles
+  schema: Schema.Schema
+}> = ({ children, lifecycle, schema }) => {
+  return (
+    <SchemaContext.Provider value={{ schema, lifecycles: lifecycle }}>
+      {children}
+    </SchemaContext.Provider>
+  )
+}
+
+export const useGraphqlLifecycle = () => {
+  const context = useContext(SchemaContext)
+  if (!context) {
+    throw new Error(`useGraphqlLifecycle must be used within a GraphqlLifecycleProvider`)
+  }
+  // Maintain backward compatibility
+  return {
+    lifecycle: context.lifecycles,
+    currentVersion: Schema.getVersion(context.schema),
+  }
+}
+
+export const useSchema = () => {
+  const context = useContext(SchemaContext)
+  if (!context) {
+    throw new Error(`useSchema must be used within a GraphqlLifecycleProvider`)
+  }
+  return context
+}

package/src/template/contexts/ThemeContext.tsx

@@ -27,7 +27,7 @@ const ThemeCSS: React.FC = () => {
 export const ThemeProvider: React.FC<{ children: React.ReactNode }> = ({ children }) => {
   const [appearance, setAppearance] = useState<ThemeAppearance>(() => {
     // Initial appearance from server or browser
-    const serverTheme = globalThis.__POLEN__.serverContext.theme
+    const serverTheme = (globalThis as any).__POLEN__.serverContext.theme
     if (serverTheme === 'system') {
       // During SSR, default to light for system preference
       // Client will detect actual preference on mount
@@ -40,7 +40,7 @@ export const ThemeProvider: React.FC<{ children: React.ReactNode }> = ({ childre
 
   const [preference, setPreference] = useState<ThemePreference>(() => {
     // Initial preference from server-rendered theme
-    const serverTheme = globalThis.__POLEN__.serverContext.theme
+    const serverTheme = (globalThis as any).__POLEN__.serverContext.theme
     // If server sent a specific theme (from cookie), use that as preference
     // Otherwise it's system preference
     return serverTheme

package/src/template/data/catalog.ts

@@ -0,0 +1,7 @@
+import { Catalog } from '#lib/catalog/$'
+import { Effect } from 'effect'
+import PROJECT_SCHEMA from 'virtual:polen/project/schema.json'
+
+export const catalog: Catalog.Catalog | null = PROJECT_SCHEMA
+  ? Effect.runSync(Catalog.decode(PROJECT_SCHEMA as any))
+  : null

package/src/template/entry.client.tsx

@@ -2,7 +2,7 @@ import '@radix-ui/themes/styles.css'
 import { ReactDomClient } from '#dep/react-dom-client/index'
 import { StrictMode } from 'react'
 import { createBrowserRouter, RouterProvider } from 'react-router'
-import PROJECT_DATA from 'virtual:polen/project/data.jsonsuper'
+import PROJECT_DATA from 'virtual:polen/project/data.json'
 import { routes } from './routes.js'
 
 // SPA
@@ -16,8 +16,12 @@ import { routes } from './routes.js'
 // SSR
 
 const router = createBrowserRouter(routes, {
-  hydrationData: window.__staticRouterHydrationData,
-  basename: PROJECT_DATA.basePath === `/` ? undefined : PROJECT_DATA.basePath.slice(0, -1), // Remove trailing slash for React Router
+  ...(window.__staticRouterHydrationData && {
+    hydrationData: window.__staticRouterHydrationData,
+  }),
+  ...(PROJECT_DATA.basePath !== '/' && {
+    basename: PROJECT_DATA.basePath.slice(0, -1), // Remove trailing slash for React Router
+  }),
 })
 
 const rootElement = document.getElementById(`app`)

package/src/template/env.d.ts

@@ -0,0 +1,3 @@
+/// <reference types="vite/client" />
+/// <reference path="../types/virtual-modules.d.ts" />
+/// <reference path="../types/global-constants.d.ts" />

package/src/template/hooks/useVersionPath.ts

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

package/src/template/layouts/ChangelogLayout.tsx

@@ -1,18 +1,16 @@
-import {
-  CRITICALITY_CONFIG,
-  isCriticalityBreaking,
-  isCriticalityDangerous,
-  isCriticalitySafe,
-} from '#lib/graphql-change/criticality'
-import { GraphqlChangeset } from '#lib/graphql-changeset'
+import { Catalog } from '#lib/catalog/$'
+import { Change } from '#lib/change/$'
+import { Revision } from '#lib/revision/$'
+import { Version } from '#lib/version/$'
 import { Box, Flex, Text } from '@radix-ui/themes'
-import type React from 'react'
-import { useEffect, useState } from 'react'
-import { renderDate } from '../components/Changelog.js'
+import React, { useEffect, useMemo, useState } from 'react'
+import { useParams } from 'react-router'
+import { renderDate } from '../components/Changelog/Changelog.js'
+import { ChangelogVersionPicker } from '../components/Changelog/ChangelogVersionPicker.js'
 
 interface ChangelogLayoutProps {
   children: React.ReactNode
-  versions: GraphqlChangeset.ChangeSet[]
+  catalog: Catalog.Catalog
 }
 
 interface VersionCounts {
@@ -21,27 +19,20 @@ interface VersionCounts {
   safe: number
 }
 
-const calculateCounts = (version: GraphqlChangeset.ChangeSet): VersionCounts => {
-  if (GraphqlChangeset.isIntermediateChangeSet(version)) {
-    return {
-      breaking: version.changes.filter(isCriticalityBreaking).length,
-      dangerous: version.changes.filter(isCriticalityDangerous).length,
-      safe: version.changes.filter(isCriticalitySafe).length,
-    }
-  }
+const calculateCounts = (revision: Revision.Revision): VersionCounts => {
   return {
-    breaking: 0,
-    dangerous: 0,
-    safe: 0,
+    breaking: revision.changes.filter(Change.isBreaking).length,
+    dangerous: revision.changes.filter(Change.isDangerous).length,
+    safe: revision.changes.filter(Change.isSafe).length,
   }
 }
 
 const SidebarEntry: React.FC<{
-  version: GraphqlChangeset.ChangeSet
+  revision: Revision.Revision
   counts: VersionCounts
   isActive: boolean
-}> = ({ version, counts, isActive }) => {
-  const dateId = version.date.toISOString()
+}> = ({ revision, counts, isActive }) => {
+  const dateId = revision.date
 
   return (
     <Box mb='2'>
@@ -60,25 +51,30 @@ const SidebarEntry: React.FC<{
         }}
         onClick={(e) => {
           e.preventDefault()
+          // Update URL hash
+          window.history.pushState(null, '', `#${dateId}`)
+          // Dispatch custom event for pushState
+          window.dispatchEvent(new Event('pushstate'))
+          // Smooth scroll to element
           document.getElementById(dateId)?.scrollIntoView({ behavior: 'smooth' })
         }}
       >
         <Text size='2' weight={isActive ? 'medium' : 'regular'}>
-          {renderDate(version.date)}
+          {renderDate(revision.date)}
         </Text>
         <Flex gap='2' align='center'>
           {counts.breaking > 0 && (
-            <Text size='1' weight='medium' style={{ color: CRITICALITY_CONFIG.BREAKING.color }}>
+            <Text size='1' weight='medium' style={{ color: '#ef4444' }}>
               {counts.breaking}
             </Text>
           )}
           {counts.dangerous > 0 && (
-            <Text size='1' weight='medium' style={{ color: CRITICALITY_CONFIG.DANGEROUS.color }}>
+            <Text size='1' weight='medium' style={{ color: '#f59e0b' }}>
               {counts.dangerous}
             </Text>
           )}
           {counts.safe > 0 && (
-            <Text size='1' weight='medium' style={{ color: CRITICALITY_CONFIG.NON_BREAKING.color }}>
+            <Text size='1' weight='medium' style={{ color: '#10b981' }}>
               {counts.safe}
             </Text>
           )}
@@ -88,46 +84,61 @@ const SidebarEntry: React.FC<{
   )
 }
 
-export const ChangelogLayout: React.FC<ChangelogLayoutProps> = ({ children, versions }) => {
-  const [activeVersion, setActiveVersion] = useState<string | null>(null)
+export const ChangelogLayout: React.FC<ChangelogLayoutProps> = ({ children, catalog }) => {
+  const [activeRevision, setActiveRevision] = useState<string | null>(null)
+  const params = useParams()
+  const urlVersion = params['version']
+
+  // Get available versions if catalog is versioned
+  const availableVersions = useMemo(() => {
+    if (Catalog.Versioned.is(catalog)) {
+      return catalog.entries.map(entry => Version.toString(entry.version))
+    }
+    return []
+  }, [catalog])
+
+  // Get revisions for the current version (for sidebar)
+  const revisions = useMemo(() => {
+    if (Catalog.Unversioned.is(catalog)) {
+      return catalog.schema.revisions
+    } else {
+      // For versioned catalogs, show only current version's revisions
+      if (urlVersion) {
+        const entry = catalog.entries.find(e => Version.toString(e.version) === urlVersion)
+        return entry ? entry.revisions : []
+      }
+      // No revisions if no version selected (will redirect)
+      return []
+    }
+  }, [catalog, urlVersion])
 
-  // Calculate counts for all versions (SSR-safe)
-  const versionsWithCounts = versions.map(version => ({
-    version,
-    counts: calculateCounts(version),
+  // Calculate counts for all revisions (SSR-safe)
+  const revisionsWithCounts = revisions.map(revision => ({
+    revision,
+    counts: calculateCounts(revision),
   }))
 
-  // Set up scroll spy after hydration
+  // Track active revision based on URL hash
   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)
+    const handleHashChange = () => {
+      const hash = window.location.hash.slice(1)
+      setActiveRevision(hash || null)
     }
 
-    // Initial check
-    handleScroll()
+    // Set initial active revision
+    handleHashChange()
 
-    // Add scroll listener
-    window.addEventListener('scroll', handleScroll, { passive: true })
+    // Listen for hash changes
+    window.addEventListener('hashchange', handleHashChange)
+
+    // Listen for pushState/replaceState (custom event we'll dispatch)
+    window.addEventListener('pushstate', handleHashChange)
 
     return () => {
-      window.removeEventListener('scroll', handleScroll)
+      window.removeEventListener('hashchange', handleHashChange)
+      window.removeEventListener('pushstate', handleHashChange)
     }
-  }, [versionsWithCounts])
+  }, [])
 
   return (
     <Flex gap='6' style={{ position: 'relative' }}>
@@ -142,15 +153,25 @@ export const ChangelogLayout: React.FC<ChangelogLayoutProps> = ({ children, vers
           overflowY: 'auto',
         }}
       >
+        {/* Version picker for versioned catalogs */}
+        {Catalog.Versioned.is(catalog) && availableVersions.length > 1 && urlVersion && (
+          <Box mb='3'>
+            <ChangelogVersionPicker
+              versions={availableVersions}
+              currentVersion={urlVersion}
+            />
+          </Box>
+        )}
+
         <Text size='2' weight='medium' mb='3' style={{ display: 'block' }}>
-          Releases
+          Revisions
         </Text>
-        {versionsWithCounts.map(({ version, counts }) => (
+        {revisionsWithCounts.map(({ revision, counts }) => (
           <SidebarEntry
-            key={version.date.toISOString()}
-            version={version}
+            key={revision.date}
+            revision={revision}
             counts={counts}
-            isActive={activeVersion === version.date.toISOString()}
+            isActive={activeRevision === revision.date}
           />
         ))}
       </Box>

package/src/template/layouts/SidebarLayout.tsx

@@ -47,8 +47,8 @@ export const SidebarLayout: React.FC<Props> = ({ children, sidebar, basePath, to
               setMobileMenuOpen(false)
             }}
             sidebarData={sidebar}
-            basePath={basePath}
-            topContent={topContent}
+            {...(basePath !== undefined && { basePath })}
+            {...(topContent !== undefined && { topContent })}
           />
         </Box>
       )}
@@ -60,7 +60,11 @@ export const SidebarLayout: React.FC<Props> = ({ children, sidebar, basePath, to
           gridColumn='1 / 3'
           gridRow='1 / auto'
         >
-          <Sidebar data={sidebar} basePath={basePath} topContent={topContent} />
+          <Sidebar
+            data={sidebar}
+            {...(basePath !== undefined && { basePath })}
+            {...(topContent !== undefined && { topContent })}
+          />
         </Box>
       )}
 

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

@@ -1,4 +1,4 @@
-import PROJECT_DATA from 'virtual:polen/project/data.jsonsuper'
+import PROJECT_DATA from 'virtual:polen/project/data.json'
 
 /**
  * Create a Polen URL path that respects the configured base path for UI navigation.

package/src/template/routes/changelog.tsx

@@ -1,42 +1,42 @@
-import type { GraphqlChangeset } from '#lib/graphql-changeset'
-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'
-import { schemaSource } from '../sources/schema-source.js'
+import { Catalog } from '#lib/catalog/$'
+import { route } from '#lib/react-router-effect/route'
+import { useLoaderData } from '#lib/react-router-effect/use-loader-data'
+import { catalogBridge } from '../catalog-bridge.js'
 
-const loader = createLoader(async () => {
-  // Check if schema exists first
-  if (schemaSource.isEmpty) {
-    return { changesets: [] }
-  }
+import { ChangelogLayout } from '#template/layouts/index'
+import { Changelog } from '../components/Changelog/Changelog.js'
 
-  // Fetch all changesets with before/after/changes data
-  const changesets = await schemaSource.getAllChangesets()
+const schema = Catalog.Catalog
 
-  return {
-    changesets,
-  }
-})
+const changelogLoader = () => catalogBridge.view()
 
 const Component = () => {
-  const data = useLoaderData<typeof loader>()
-
-  if (data.changesets.length === 0) {
-    return <div>No schema versions available for changelog.</div>
-  }
+  const catalog = useLoaderData(schema)
 
   return (
-    <ChangelogLayout versions={data.changesets}>
-      <Changelog
-        changesets={data.changesets as [GraphqlChangeset.ChangeSet, ...GraphqlChangeset.ChangeSet[]]}
-      />
+    <ChangelogLayout catalog={catalog}>
+      <Changelog catalog={catalog} />
     </ChangelogLayout>
   )
 }
 
 export const changelog = route({
+  schema,
   path: `changelog`,
-  loader,
+  loader: changelogLoader,
   Component,
+  children: [
+    // Support deep linking to specific version
+    route({
+      path: `version/:version`,
+      loader: changelogLoader,
+      Component,
+    }),
+    // Support deep linking to specific version/revision
+    route({
+      path: `version/:version/revision/:revision`,
+      loader: changelogLoader,
+      Component,
+    }),
+  ],
 })

package/src/template/routes/index.tsx

@@ -1,4 +1,4 @@
-import { routeIndex } from '#lib/react-router-aid/react-router-aid'
+import { routeIndex } from '#lib/react-router-effect/react-router-effect'
 import { Box } from '@radix-ui/themes'
 
 const Component = () => {

package/src/template/routes/pages.tsx

@@ -1,5 +1,4 @@
-import { route } from '#lib/react-router-aid/react-router-aid'
-import { createLoader, useLoaderData } from '#lib/react-router-loader/react-router-loader'
+import { route } from '#lib/react-router-effect/route'
 import { SidebarLayout } from '#template/layouts/index'
 import { MDXProvider } from '@mdx-js/react'
 import {
@@ -22,24 +21,11 @@ import {
   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 PROJECT_DATA_PAGES_CATALOG from 'virtual:polen/project/data/pages-catalog.json'
 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
@@ -90,8 +76,8 @@ const Component = () => {
         Tabs,
         Tooltip,
 
-        // Code Hike component with schema injected
-        CodeBlock: (props: any) => <CodeBlock {...props} schema={schema} />,
+        // Code Hike component - schema will be loaded client-side if needed
+        CodeBlock: (props: any) => <CodeBlock {...props} schema={null} />,
       }}
     >
       <SidebarLayout sidebar={sidebar}>
@@ -103,7 +89,6 @@ const Component = () => {
 
 export const pages = route({
   // Pathless layout route - doesn't affect URL paths
-  loader,
   Component,
   children: [...routes], // All MDX page routes go here
 })