polen 0.11.0-next.10 → 0.11.0-next.12

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/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/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/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/reference.tsx

@@ -1,23 +1,24 @@
 import type { Content } from '#api/content/$'
+import { Api } from '#api/iso'
+import type { React } from '#dep/react/index'
 import { GrafaidOld } from '#lib/grafaid-old/index'
-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, 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 { SidebarLayout } from '../layouts/index.js'
-import { VERSION_LATEST } from '../lib/schema-utils/constants.js'
 import { schemaSource } from '../sources/schema-source.js'
 
 export const loader = createLoader(async ({ params }) => {
   // Handle both versioned and unversioned routes:
   // - Versioned: /reference/version/:version/:type → params.version exists
   // - Unversioned: /reference/:type → params.version is undefined, defaults to latest
-  const currentVersion = params.version ?? VERSION_LATEST
+  const currentVersion = params.version ?? Api.Schema.VERSION_LATEST
 
   const schema = await schemaSource.get(currentVersion)
   const availableVersions = schemaSource.versions
@@ -29,7 +30,9 @@ export const loader = createLoader(async ({ params }) => {
   }
 })
 
-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) {
@@ -42,12 +45,6 @@ const RouteReferenceComponent = () => {
   const sidebarItems: Content.Item[] = []
   const kindEntries = Object.entries(kindMap.list).filter(([_, types]) => types.length > 0)
 
-  // Build path prefix based on current version from loader data
-  // This ensures sidebar links always match the current version being viewed
-  const versionPath = data.currentVersion === VERSION_LATEST
-    ? ``
-    : `version/${data.currentVersion}/`
-
   for (const [title, types] of kindEntries) {
     sidebarItems.push({
       type: `ItemSection` as const,
@@ -57,96 +54,82 @@ const RouteReferenceComponent = () => {
       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)
+
+  // 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} />
+    } else {
+      neverCase(viewType)
+    }
+  })()
+
   return (
-    <SidebarLayout sidebar={sidebarItems}>
+    <SidebarLayout sidebar={sidebarItems} basePath={basePath}>
       <Box mb={`4`}>
-        <VersionSelector
-          availableVersions={data.availableVersions}
-          currentVersion={data.currentVersion}
+        <VersionPicker
+          all={[...data.availableVersions]} // Convert readonly to mutable
+          current={data.currentVersion}
         />
       </Box>
-      <Outlet />
+      {content}
     </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>
-}
-
-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} />
-}
-
+// 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,7 +49,12 @@ 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 }}>
@@ -61,7 +69,7 @@ const Layout = () => {
   )
 
   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 +80,13 @@ const Layout = () => {
       >
         {header}
         <Outlet />
+        <ToastContainer />
       </Box>
     </Theme>
   )
 }
 
-const children: ReactRouter.RouteObject[] = [
-  index,
-  pages,
-]
+const children: ReactRouter.RouteObject[] = [index, pages]
 
 //
 //
@@ -122,8 +128,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/ssg/get-route-paths.test.ts

@@ -50,6 +50,19 @@ vi.mock('#api/index', () => ({
     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}`
+        }),
+      },
     },
   },
 }))