polen 0.11.0-next.11 → 0.11.0-next.13

package/src/template/components/VersionPicker.tsx

@@ -0,0 +1,94 @@
+import { Api } from '#api/iso'
+import type { React } from '#dep/react/index'
+import { Select } from '@radix-ui/themes'
+import { useNavigate } from 'react-router'
+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
+}
+
+export const VersionPicker: React.FC<Props> = ({ all, current }) => {
+  const navigate = useNavigate()
+  const currentPath = useReferencePath()
+
+  // Don't show selector if only one version
+  if (all.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)
+      // Find fallback path if needed
+      const fallbackPath = Api.Schema.Validation.findFallbackPath(targetSchema, currentPath)
+      // Get redirect description if path changed
+      const redirectDescription = Api.Schema.Validation.getRedirectDescription(
+        targetSchema,
+        currentPath,
+        fallbackPath,
+        newVersion,
+      )
+      // Create the new path
+      const newPath = Api.Schema.Routing.createReferencePath({
+        version: newVersion,
+        type: fallbackPath.type,
+        field: fallbackPath.field,
+      })
+      // Show toast notification if schema location redirect will occur
+      if (redirectDescription) {
+        Stores.Toast.store.info(redirectDescription, {
+          duration: 160_000,
+          actions: [
+            {
+              label: 'Go back',
+              onClick() {
+                navigate(-1)
+              },
+            },
+            {
+              label: 'View changelog',
+              onClick() {
+                // Navigate to changelog page
+                navigate('/changelog')
+              },
+            },
+          ],
+        })
+      }
+
+      navigate(newPath)
+    }, 'Failed to switch version')
+
+    // Fallback logic if error occurred
+    if (error) {
+      // Fallback to simple navigation if schema loading fails
+      const newPath = Api.Schema.Routing.createReferencePath({
+        version: newVersion,
+        type: currentPath.type,
+        field: currentPath.field,
+      })
+      navigate(newPath)
+    }
+  }
+
+  return (
+    <Select.Root value={current} onValueChange={handleVersionChange}>
+      <Select.Trigger>
+        {current === Api.Schema.VERSION_LATEST ? `Latest` : current}
+      </Select.Trigger>
+      <Select.Content>
+        {all.map(version => (
+          <Select.Item key={version} value={version}>
+            {version === Api.Schema.VERSION_LATEST ? `Latest` : version}
+          </Select.Item>
+        ))}
+      </Select.Content>
+    </Select.Root>
+  )
+}

package/src/template/components/graphql/type-kind-icon.tsx

@@ -1,5 +1,5 @@
 import type { React } from '#dep/react/index'
-import type { Grafaid } from '#lib/grafaid/index'
+import type { Grafaid } from '#lib/grafaid'
 import { Code } from '@radix-ui/themes'
 import { typeKindTokensIndex, unknownTypeKindToken } from './type-kind-tokens.js'
 

package/src/template/components/graphql/type-kind-tokens.ts

@@ -1,4 +1,4 @@
-import type { Grafaid } from '#lib/grafaid/index'
+import type { Grafaid } from '#lib/grafaid'
 import type { colorPropDef } from '@radix-ui/themes/props'
 
 type RadixColor = typeof colorPropDef[`color`][`values`][number]

package/src/template/components/graphql/type-link.tsx

@@ -1,4 +1,4 @@
-import { Grafaid } from '#lib/grafaid/index'
+import { Grafaid } from '#lib/grafaid'
 import { Code, Flex } from '@radix-ui/themes'
 import { ReferenceLink } from '../ReferenceLink.js'
 import { TypeKindIcon } from './graphql.js'

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

@@ -8,9 +8,10 @@ interface Props extends LayoutProps, MarginProps, BoxOwnProps {
   data: Content.Item[]
   basePath?: string
   style?: React.CSSProperties
+  topContent?: React.ReactNode
 }
 
-export const Sidebar = ({ data, basePath, ...props }: Props) => {
+export const Sidebar = ({ data, basePath, topContent, ...props }: Props) => {
   return (
     <SidebarContext.Provider value={{ basePath }}>
       <Box
@@ -25,6 +26,11 @@ export const Sidebar = ({ data, basePath, ...props }: Props) => {
             }
           `}
         </style>
+        {topContent && (
+          <Box mb='4'>
+            {topContent}
+          </Box>
+        )}
         <Items items={data} />
       </Box>
     </SidebarContext.Provider>

package/src/template/contexts/SchemaLifecycleContext.tsx

@@ -0,0 +1,30 @@
+import type { React } from '#dep/react/index'
+import { SchemaLifecycle } from '#lib/schema-lifecycle'
+import { createContext, useContext } from 'react'
+
+interface SchemaLifecycleContextValue {
+  lifecycle: SchemaLifecycle.SchemaLifecycle | null
+  currentVersion: string
+}
+
+const SchemaLifecycleContext = createContext<SchemaLifecycleContextValue | undefined>(undefined)
+
+export const SchemaLifecycleProvider: React.FC<{
+  children: React.ReactNode
+  lifecycle: SchemaLifecycle.SchemaLifecycle | null
+  currentVersion: string
+}> = ({ children, lifecycle, currentVersion }) => {
+  return (
+    <SchemaLifecycleContext.Provider value={{ lifecycle, currentVersion }}>
+      {children}
+    </SchemaLifecycleContext.Provider>
+  )
+}
+
+export const useSchemaLifecycle = () => {
+  const context = useContext(SchemaLifecycleContext)
+  if (!context) {
+    throw new Error(`useSchemaLifecycle must be used within a SchemaLifecycleProvider`)
+  }
+  return context
+}

package/src/template/hooks/useReferencePath.ts

@@ -0,0 +1,20 @@
+import { Api } from '#api/iso'
+import { useLocation, useParams } from 'react-router'
+
+/**
+ * Hook that returns parsed reference path parameters
+ *
+ * @throws {Error} If not currently on a reference route
+ * @returns Parsed reference path object
+ */
+export const useReferencePath = (): Api.Schema.Validation.PathValidation => {
+  const params = useParams()
+  const location = useLocation()
+
+  Api.Schema.Routing.assertReferenceRoute({
+    pathname: location.pathname,
+    params,
+  })
+
+  return params
+}

package/src/template/layouts/ChangelogLayout.tsx

@@ -4,7 +4,7 @@ import {
   isCriticalityDangerous,
   isCriticalitySafe,
 } from '#lib/graphql-change/criticality'
-import type { GraphqlChangeset } from '#lib/graphql-changeset/index'
+import { GraphqlChangeset } from '#lib/graphql-changeset'
 import { Box, Flex, Text } from '@radix-ui/themes'
 import type React from 'react'
 import { useEffect, useState } from 'react'
@@ -22,10 +22,17 @@ interface VersionCounts {
 }
 
 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,
+    }
+  }
   return {
-    breaking: version.changes.filter(isCriticalityBreaking).length,
-    dangerous: version.changes.filter(isCriticalityDangerous).length,
-    safe: version.changes.filter(isCriticalitySafe).length,
+    breaking: 0,
+    dangerous: 0,
+    safe: 0,
   }
 }
 

package/src/template/layouts/SidebarLayout.tsx

@@ -10,9 +10,10 @@ interface Props {
   children: React.ReactNode
   sidebar: Content.Item[]
   basePath?: string
+  topContent?: React.ReactNode
 }
 
-export const SidebarLayout: React.FC<Props> = ({ children, sidebar, basePath }) => {
+export const SidebarLayout: React.FC<Props> = ({ children, sidebar, basePath, topContent }) => {
   const location = useLocation()
   const [mobileMenuOpen, setMobileMenuOpen] = useState(false)
 
@@ -47,6 +48,7 @@ export const SidebarLayout: React.FC<Props> = ({ children, sidebar, basePath })
             }}
             sidebarData={sidebar}
             basePath={basePath}
+            topContent={topContent}
           />
         </Box>
       )}
@@ -58,7 +60,7 @@ export const SidebarLayout: React.FC<Props> = ({ children, sidebar, basePath })
           gridColumn='1 / 3'
           gridRow='1 / auto'
         >
-          <Sidebar data={sidebar} basePath={basePath} />
+          <Sidebar data={sidebar} basePath={basePath} topContent={topContent} />
         </Box>
       )}
 

package/src/template/routes/changelog.tsx

@@ -1,4 +1,4 @@
-import type { GraphqlChangeset } from '#lib/graphql-changeset/index'
+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'
@@ -28,7 +28,9 @@ const Component = () => {
 
   return (
     <ChangelogLayout versions={data.changesets}>
-      <Changelog changesets={data.changesets as [GraphqlChangeset.ChangeSet, ...GraphqlChangeset.ChangeSet[]]} />
+      <Changelog
+        changesets={data.changesets as [GraphqlChangeset.ChangeSet, ...GraphqlChangeset.ChangeSet[]]}
+      />
     </ChangelogLayout>
   )
 }

package/src/template/routes/reference.tsx

@@ -1,15 +1,17 @@
 import type { Content } from '#api/content/$'
 import { Api } from '#api/iso'
-import { GrafaidOld } from '#lib/grafaid-old/index'
-import { Grafaid } from '#lib/grafaid/index'
+import type { React } from '#dep/react/index'
+import { GrafaidOld } from '#lib/grafaid-old'
 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, useParams } from 'react-router'
+import { neverCase } from '@wollybeard/kit/language'
+import { 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 { VersionPicker } from '../components/VersionPicker.js'
+import { SchemaLifecycleProvider } from '../contexts/SchemaLifecycleContext.js'
 import { SidebarLayout } from '../layouts/index.js'
 import { schemaSource } from '../sources/schema-source.js'
 
@@ -22,14 +24,20 @@ export const loader = createLoader(async ({ params }) => {
   const schema = await schemaSource.get(currentVersion)
   const availableVersions = schemaSource.versions
 
+  // Load lifecycle data if available
+  const lifecycle = await schemaSource.getLifecycle()
+
   return {
     schema,
     currentVersion,
     availableVersions,
+    lifecycle,
   }
 })
 
-const RouteReferenceComponent = () => {
+// Single component that handles all reference route variations
+const ReferenceView = () => {
+  const params = useParams() as { version?: string; type?: string; field?: string }
   const data = useLoaderData<typeof loader>()
 
   if (!data.schema) {
@@ -59,91 +67,84 @@ const RouteReferenceComponent = () => {
   // Calculate basePath based on current version
   const basePath = Api.Schema.Routing.createReferenceBasePath(data.currentVersion)
 
-  return (
-    <SidebarLayout sidebar={sidebarItems} basePath={basePath}>
-      <Box mb={`4`}>
-        <VersionSelector
-          availableVersions={data.availableVersions}
-          currentVersion={data.currentVersion}
+  // Determine view type and render appropriate content
+  const viewType = Api.Schema.Routing.getReferenceViewType({
+    schema: data.schema,
+    type: params.type,
+    field: params.field,
+  })
+
+  const content: React.ReactNode = (() => {
+    if (viewType === 'index') {
+      return <div>Select a type from the sidebar to view its documentation.</div>
+    } else if (viewType === 'type-missing' || viewType === 'field-missing') {
+      return <MissingSchema />
+    } else if (viewType === 'type') {
+      const type = data.schema.getType(params.type!)!
+      return <NamedType data={type} />
+    } else if (viewType === 'field') {
+      const type = data.schema.getType(params.type!)!
+      const fields = (type as any).getFields()
+      const field = fields[params.field!]
+      return (
+        <Field
+          data={field}
+          parentTypeName={params.type!}
         />
-      </Box>
-      <Outlet />
-    </SidebarLayout>
-  )
-}
-
-// 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>
-}
+      )
+    } else {
+      neverCase(viewType)
+    }
+  })()
 
-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} />
+  return (
+    <SchemaLifecycleProvider lifecycle={data.lifecycle} currentVersion={data.currentVersion}>
+      <SidebarLayout
+        sidebar={sidebarItems}
+        basePath={basePath}
+        topContent={
+          <VersionPicker
+            all={[...data.availableVersions]} // Convert readonly to mutable
+            current={data.currentVersion}
+          />
+        }
+      >
+        {content}
+      </SidebarLayout>
+    </SchemaLifecycleProvider>
+  )
 }
 
+// Define routes that handle type and field params
 const typeAndFieldRoutes = [
-  routeIndex(RouteComponentIndex),
+  routeIndex({
+    Component: ReferenceView,
+    loader,
+  }),
   route({
     path: `:type`,
-    Component: RouteComponentType,
+    Component: ReferenceView,
     errorElement: <MissingSchema />,
+    loader,
     children: [
       route({
         path: `:field`,
-        Component: RouteComponentTypeField,
+        Component: ReferenceView,
         errorElement: <MissingSchema />,
+        loader,
       }),
     ],
   }),
 ]
 
 /**
- * Reference documentation with proper nested structure - all routes in one file
+ * Reference documentation routes using proper React Router patterns
+ * - Parent routes have no components (automatically render Outlet)
+ * - Leaf routes have components and loaders that always run fresh
+ * - Single ReferenceView component handles all variations
  */
 export const reference = route({
-  id: 'reference',
   path: `reference`,
-  loader,
-  Component: RouteReferenceComponent,
   children: [
     ...typeAndFieldRoutes,
     route({

package/src/template/routes/root.tsx

@@ -1,5 +1,7 @@
 import type { ReactRouter } from '#dep/react-router/index'
 import { route } from '#lib/react-router-aid/react-router-aid'
+import { createLoader } from '#lib/react-router-loader/react-router-loader'
+import type { Stores } from '#template/stores/$'
 import { Box, Flex, Theme } from '@radix-ui/themes'
 import { Link as LinkReactRouter } from 'react-router'
 import { Outlet, ScrollRestoration } from 'react-router'
@@ -11,6 +13,7 @@ import { Link as PolenLink } from '../components/Link.js'
 import { Logo } from '../components/Logo.js'
 import { NotFound } from '../components/NotFound.js'
 import { ThemeToggle } from '../components/ThemeToggle.js'
+import { ToastContainer } from '../components/ToastContainer.js'
 import { ThemeProvider, useTheme } from '../contexts/ThemeContext.js'
 import { changelog } from './changelog.js'
 import { index } from './index.js'
@@ -46,22 +49,38 @@ const Layout = () => {
         style={{ color: `inherit`, textDecoration: `none` }}
       >
         <Box display={{ initial: `block`, md: `block` }}>
-          <Logo src={logoSrc} title={templateVariables.title} height={30} showTitle={true} />
+          <Logo
+            src={logoSrc}
+            title={templateVariables.title}
+            height={30}
+            showTitle={true}
+          />
         </Box>
       </LinkReactRouter>
       <Flex direction='row' gap='4' style={{ flex: 1 }}>
-        {PROJECT_DATA.navbar.map((item, key) => (
-          <PolenLink key={key} color='gray' to={item.pathExp}>
-            {item.title}
-          </PolenLink>
-        ))}
+        {PROJECT_DATA.navbar
+          .filter(item => item.position !== 'right')
+          .map((item, key) => (
+            <PolenLink key={key} color='gray' to={item.pathExp}>
+              {item.title}
+            </PolenLink>
+          ))}
+      </Flex>
+      <Flex direction='row' gap='4'>
+        {PROJECT_DATA.navbar
+          .filter(item => item.position === 'right')
+          .map((item, key) => (
+            <PolenLink key={key} color='gray' to={item.pathExp}>
+              {item.title}
+            </PolenLink>
+          ))}
       </Flex>
       <ThemeToggle />
     </Flex>
   )
 
   return (
-    <Theme asChild appearance={appearance}>
+    <Theme asChild appearance={appearance} radius='none'>
       <Box
         width={{ initial: `100%`, sm: `100%`, md: `var(--container-4)` }}
         maxWidth='100vw'
@@ -72,15 +91,13 @@ const Layout = () => {
       >
         {header}
         <Outlet />
+        <ToastContainer />
       </Box>
     </Theme>
   )
 }
 
-const children: ReactRouter.RouteObject[] = [
-  index,
-  pages,
-]
+const children: ReactRouter.RouteObject[] = [index, pages]
 
 //
 //
@@ -122,8 +139,25 @@ children.push(notFoundRoute)
 //
 //
 
+const storeModules = import.meta.glob('../stores/!($.*)*.ts', { eager: true }) as Record<
+  string,
+  Stores.StoreModule
+>
+
 export const root = route({
   path: `/`,
   Component,
+  loader: createLoader(async () => {
+    // Reset all stores on SSR to prevent cross-request pollution
+    if (import.meta.env.SSR) {
+      for (const module of Object.values(storeModules)) {
+        if (module.store?.reset) {
+          module.store.reset()
+        }
+      }
+    }
+
+    return {}
+  }),
   children,
 })

package/src/template/server/create-page-html-response.ts

@@ -3,7 +3,7 @@ import type { Hono } from '#dep/hono/index'
 import type { ReactRouter } from '#dep/react-router/index'
 import { React } from '#dep/react/index'
 import { ResponseInternalServerError } from '#lib/kit-temp'
-import type { ReactRouterAid } from '#lib/react-router-aid/index'
+import type { ReactRouterAid } from '#lib/react-router-aid'
 import * as Theme from '#lib/theme/theme'
 import { Arr } from '@wollybeard/kit'
 import * as ReactDomServer from 'react-dom/server'

package/src/template/server/middleware/unsupported-assets.ts

@@ -1,6 +1,6 @@
 import type { Hono } from '#dep/hono/index'
-import { AppleTouchIcon } from '#lib/apple-touch-icon/index'
-import { Favicon } from '#lib/favicon/index'
+import { AppleTouchIcon } from '#lib/apple-touch-icon'
+import { Favicon } from '#lib/favicon'
 import { Http } from '@wollybeard/kit'
 
 /**

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

@@ -1,5 +1,5 @@
 import { Api } from '#api/index'
-import { ReactRouterAid } from '#lib/react-router-aid/index'
+import { ReactRouterAid } from '#lib/react-router-aid'
 import { visit } from 'graphql'
 import * as NodeFs from 'node:fs/promises'
 import * as NodePath from 'node:path'

package/src/template/stores/$$.ts

@@ -0,0 +1,15 @@
+export * as Schema from './schema.js'
+export { store as schema } from './schema.js'
+
+export * as Toast from './toast.js'
+export { store as toast } from './toast.js'
+
+export interface Store {
+  reset: () => void
+  set: (data?: unknown) => void
+}
+
+export interface StoreModule {
+  store: Store
+  initialState: unknown
+}

package/src/template/stores/$.ts

@@ -0,0 +1 @@
+export * as Stores from './$$.js'

package/src/template/stores/schema.ts

@@ -0,0 +1,52 @@
+import type { GraphQLSchema } from 'graphql'
+import { proxy, ref } from 'valtio'
+
+/**
+ * Schema store state interface
+ */
+export interface State {
+  /** Currently selected schema version */
+  currentVersion: string
+  /** All available schema versions */
+  availableVersions: string[]
+  /** Currently loaded GraphQL schema instance */
+  currentSchema: GraphQLSchema | null
+}
+
+/**
+ * Initial state for the schema store
+ */
+export const initialState: State = {
+  currentVersion: 'latest',
+  availableVersions: [],
+  currentSchema: null,
+}
+
+/**
+ * Schema store
+ *
+ * Manages GraphQL schema state including version selection and schema instances.
+ * Used for version switching and schema-aware navigation.
+ */
+export const store = proxy({
+  ...initialState,
+
+  /**
+   * Reset store to initial state
+   */
+  reset() {
+    Object.assign(store, initialState)
+  },
+
+  /**
+   * Set store state
+   * @param data - New state data
+   */
+  set(data: State) {
+    // Set each property individually to avoid issues with complex objects
+    store.currentVersion = data.currentVersion
+    store.availableVersions = data.availableVersions
+    // Use ref() to prevent Valtio from deeply proxying the GraphQL schema
+    store.currentSchema = data.currentSchema ? ref(data.currentSchema) : null
+  },
+})