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

package/src/template/components/ThemeToggle.tsx

@@ -1,21 +1,43 @@
 import type { React } from '#dep/react/index'
-import { MoonIcon, SunIcon } from '@radix-ui/react-icons'
+import { DesktopIcon, MoonIcon, SunIcon } from '@radix-ui/react-icons'
 import { IconButton } from '@radix-ui/themes'
-import { useTheme } from '../contexts/ThemeContext.tsx'
+import { useTheme } from '../contexts/ThemeContext.js'
 
 export const ThemeToggle: React.FC = () => {
-  const { appearance, toggleTheme } = useTheme()
+  const { appearance, toggleTheme, preference } = useTheme()
+
+  const handleClick = () => {
+    toggleTheme()
+  }
+
+  // Determine next state in cycle: system → light → dark → system
+  const getNextTheme = () => {
+    if (!preference || preference === 'system') return 'light'
+    if (preference === 'light') return 'dark'
+    return 'system'
+  }
+
+  const getIcon = () => {
+    // Show icon based on preference, not appearance
+    if (!preference || preference === 'system') {
+      return <DesktopIcon width='18' height='18' />
+    }
+    if (preference === 'light') {
+      return <SunIcon width='18' height='18' />
+    }
+    return <MoonIcon width='18' height='18' />
+  }
 
   return (
     <IconButton
       size='2'
       variant='ghost'
       color='gray'
-      onClick={toggleTheme}
-      aria-label={`Switch to ${appearance === 'light' ? 'dark' : 'light'} theme`}
-      style={{ cursor: 'pointer' }}
+      onClick={handleClick}
+      aria-label={`Switch to ${getNextTheme()} theme`}
+      style={{ cursor: `pointer` }}
     >
-      {appearance === 'light' ? <MoonIcon width='18' height='18' /> : <SunIcon width='18' height='18' />}
+      {getIcon()}
     </IconButton>
   )
 }

package/src/template/components/TypeAnnotation.tsx

@@ -2,7 +2,7 @@ import { Text } from '@radix-ui/themes'
 import type { GraphQLType } from 'graphql'
 import { isInputObjectType, isListType, isNamedType, isNonNullType, isScalarType } from 'graphql'
 import type { FC } from 'react'
-import { Link } from './Link.jsx'
+import { ReferenceLink } from './ReferenceLink.js'
 
 export interface Props {
   type: GraphQLType // Can be either GraphQLInputType or GraphQLOutputType
@@ -40,20 +40,18 @@ export const TypeAnnotation: FC<Props> = ({ type }) => {
     // Handle input object types
     if (isInputObjectType(namedType)) {
       return (
-        <Link
-          to={`/reference/${namedType.name}`}
-        >
+        <ReferenceLink type={namedType.name}>
           <Text color='green'>{namedType.name}</Text>
-        </Link>
+        </ReferenceLink>
       )
     }
 
     // If it's an expandable type (object or interface), make it a link
     // if (Grafaid.isExpandableType(namedType)) {
     return (
-      <Link to={`/reference/${namedType.name}`}>
+      <ReferenceLink type={namedType.name}>
         <Text color={isScalarType(namedType) ? `purple` : `blue`}>{namedType.name}</Text>
-      </Link>
+      </ReferenceLink>
     )
 
     // For scalar and other non-expandable types, just render the name

package/src/template/components/TypeFieldsLinkList.tsx

@@ -1,7 +1,7 @@
 import { Box, Flex, Heading } from '@radix-ui/themes'
 import type { GraphQLInterfaceType, GraphQLObjectType } from 'graphql'
 import type { FC } from 'react'
-import { Link } from './Link.jsx'
+import { ReferenceLink } from './ReferenceLink.js'
 
 export interface Props {
   type: GraphQLObjectType | GraphQLInterfaceType
@@ -9,27 +9,24 @@ export interface Props {
 
 export const TypeFieldsLinkList: FC<Props> = ({ type }) => {
   return (
-    (
-      <Box>
-        <Heading>{type.name}</Heading>
-        <Flex direction='column'>
-          {Object.values(type.getFields()).map(field => {
-            return (
-              (
-                <Box key={field.name}>
-                  <Link
-                    to={`/reference/${type.name}/${field.name}`}
-                    // TODO: can we use styled from Radix?
-                    // activeProps={{ style: { fontWeight: `bold` } }}
-                  >
-                    {field.name}
-                  </Link>
-                </Box>
-              )
-            )
-          })}
-        </Flex>
-      </Box>
-    )
+    <Box>
+      <Heading>{type.name}</Heading>
+      <Flex direction='column'>
+        {Object.values(type.getFields()).map(field => {
+          return (
+            <Box key={field.name}>
+              <ReferenceLink
+                type={type.name}
+                field={field.name}
+                // TODO: can we use styled from Radix?
+                // activeProps={{ style: { fontWeight: `bold` } }}
+              >
+                {field.name}
+              </ReferenceLink>
+            </Box>
+          )
+        })}
+      </Flex>
+    </Box>
   )
 }

package/src/template/components/TypeIndex.tsx

@@ -3,7 +3,7 @@ import { Box, Flex, Heading } from '@radix-ui/themes'
 import { Obj } from '@wollybeard/kit'
 import type { GraphQLNamedType, GraphQLSchema } from 'graphql'
 import type { FC } from 'react'
-import { Link } from './Link.jsx'
+import { ReferenceLink } from './ReferenceLink.js'
 
 export interface Props {
   schema: GraphQLSchema
@@ -31,16 +31,14 @@ const TypeSection: FC<{ title: string; types: GraphQLNamedType[] }> = ({ title,
 
 const TypeList: FC<{ types: GraphQLNamedType[] }> = ({ types }) => {
   return (
-    (
-      <Box>
-        {types.map(type => (
-          <Box key={type.name}>
-            <Link to={`/reference/${type.name}`}>
-              {type.name}
-            </Link>
-          </Box>
-        ))}
-      </Box>
-    )
+    <Box>
+      {types.map(type => (
+        <Box key={type.name}>
+          <ReferenceLink type={type.name}>
+            {type.name}
+          </ReferenceLink>
+        </Box>
+      ))}
+    </Box>
   )
 }

package/src/template/components/VersionSelector.tsx

@@ -0,0 +1,50 @@
+import { Select } from '@radix-ui/themes'
+import { useNavigate, useParams } from 'react-router'
+import { VERSION_LATEST } from '../lib/schema-utils/constants.js'
+
+interface VersionSelectorProps {
+  availableVersions: string[]
+  currentVersion: string
+}
+
+export const VersionSelector = ({ availableVersions, currentVersion }: VersionSelectorProps) => {
+  const navigate = useNavigate()
+  const params = useParams()
+
+  // Don't show selector if only one version
+  if (availableVersions.length <= 1) {
+    return null
+  }
+
+  const handleVersionChange = (newVersion: string) => {
+    // Build new path preserving the current type/field if any
+    const currentType = params[`type`]
+    const currentField = params[`field`]
+
+    let newPath = `/reference`
+    if (newVersion !== VERSION_LATEST) {
+      newPath += `/version/${newVersion}`
+    }
+    if (currentType) {
+      newPath += `/${currentType}`
+      if (currentField) {
+        newPath += `/${currentField}`
+      }
+    }
+
+    navigate(newPath)
+  }
+
+  return (
+    <Select.Root value={currentVersion} onValueChange={handleVersionChange}>
+      <Select.Trigger />
+      <Select.Content>
+        {availableVersions.map(version => (
+          <Select.Item key={version} value={version}>
+            {version === VERSION_LATEST ? `Latest` : version}
+          </Select.Item>
+        ))}
+      </Select.Content>
+    </Select.Root>
+  )
+}

package/src/template/components/graphql/graphql.tsx

@@ -1,2 +1,2 @@
-export * from './type-kind-icon.jsx'
-export * from './type-link.jsx'
+export * from './type-kind-icon.js'
+export * from './type-link.js'

package/src/template/components/graphql/index.ts

@@ -1 +1 @@
-export * as Graphql from './graphql.jsx'
+export * as Graphql from './graphql.js'

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

@@ -1,10 +1,9 @@
 import type { React } from '#dep/react/index'
 import type { Grafaid } from '#lib/grafaid/index'
 import { Code } from '@radix-ui/themes'
-import { typeKindTokensIndex, unknownTypeKindToken } from './type-kind-tokens.ts'
+import { typeKindTokensIndex, unknownTypeKindToken } from './type-kind-tokens.js'
 
 export const TypeKindIcon: React.FC<{ kind: Grafaid.Schema.TypeKindName }> = ({ kind }) => {
-  // eslint-disable-next-line
   const { symbol, color } = typeKindTokensIndex[kind] ?? unknownTypeKindToken
 
   return <Code color={color} weight='bold' variant='outline'>{symbol}</Code>

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

@@ -1,18 +1,19 @@
 import { Grafaid } from '#lib/grafaid/index'
 import { Code, Flex } from '@radix-ui/themes'
-import { Link } from '../Link.jsx'
-import { TypeKindIcon } from './graphql.jsx'
-import { typeKindTokensIndex } from './type-kind-tokens.ts'
+import { ReferenceLink } from '../ReferenceLink.js'
+import { TypeKindIcon } from './graphql.js'
+import { typeKindTokensIndex } from './type-kind-tokens.js'
 
 export const TypeLink: React.FC<{ type: Grafaid.Schema.TypesLike.Named }> = ({ type }) => {
   const kind = Grafaid.Schema.typeKindFromClass(type)
+
   return (
-    <Link to={`/reference/${type.name}`}>
+    <ReferenceLink type={type.name}>
       <Flex align='center' gap='1' display='inline-flex'>
         <TypeKindIcon kind={kind} />
         {` `}
         <Code color={typeKindTokensIndex[kind].color} variant='ghost'>{type.name}</Code>
       </Flex>
-    </Link>
+    </ReferenceLink>
   )
 }

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

@@ -1,7 +1,7 @@
 import type { Content } from '#api/content/$'
 import { Box } from '@radix-ui/themes'
 import type { BoxOwnProps, LayoutProps, MarginProps } from '@radix-ui/themes/props'
-import { Items } from './SidebarItem.tsx'
+import { Items } from './SidebarItem.js'
 
 interface SidebarProps extends LayoutProps, MarginProps, BoxOwnProps {
   data: Content.Item[]

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

@@ -3,14 +3,14 @@ import type { React } from '#dep/react/index'
 import { Texts } from '#template/components/Texts/index'
 import { Box, Flex } from '@radix-ui/themes'
 import { useLocation } from 'react-router'
-import { getPathActiveReport, Link } from '../Link.tsx'
+import { getPathActiveReport, Link } from '../Link.js'
 
 export const Items: React.FC<{ items: Content.Item[] }> = ({ items }) => {
   return (
     <Flex direction='column' gap='2px'>
-      {items.map((item) => (
+      {items.map((item, index) => (
         <Item
-          key={item.pathExp}
+          key={`${item.pathExp}-${index}`}
           item={item}
         />
       ))}
@@ -31,7 +31,7 @@ export const Item: React.FC<{ item: Content.Item }> = ({ item }) => {
     return <SBLink link={item} />
   }
 
-  if (item.type === 'ItemSection' && item.isLinkToo) {
+  if (item.type === `ItemSection` && item.isLinkToo) {
     return <LinkedSection section={item} />
   }
 
@@ -63,7 +63,7 @@ const SBLink: React.FC<{
         display: `block`,
         textDecoration: `none`,
         color: active.is ? `var(--accent-12)` : undefined,
-        backgroundColor: active.isDirect ? `var(--accent-2)` : active.isdescendant ? `var(--accent-1)` : `transparent`,
+        backgroundColor: active.isDirect ? `var(--accent-2)` : active.isDescendant ? `var(--accent-1)` : `transparent`,
         borderRadius: `var(--radius-2)`,
       }}
     >
@@ -113,7 +113,7 @@ const LinkedSection: React.FC<{
         <Flex
           direction='column'
           gap='2'
-          id={`section-${section.pathExp.replace(/\//g, '-')}`}
+          id={`section-${section.pathExp.replace(/\//g, `-`)}`}
           role='group'
           ml='5'
           py='2px'
@@ -121,9 +121,9 @@ const LinkedSection: React.FC<{
             borderLeft: `1px solid var(--gray-5)`,
           }}
         >
-          {section.links.map((link) => (
+          {section.links.map((link, index) => (
             <SectionLink
-              key={link.pathExp}
+              key={`${link.pathExp}-${index}`}
               link={link}
             />
           ))}
@@ -140,12 +140,12 @@ const SectionLink: React.FC<{ link: Content.ItemLink }> = ({ link }) => {
   return (
     <Link
       role='Sidebar Link'
-      to={'/' + link.pathExp}
+      to={`/` + link.pathExp}
       color={active.is ? `iris` : `gray`}
       style={{
         textDecoration: `none`,
         color: active.is ? `var(--accent-12)` : undefined,
-        backgroundColor: active.isDirect ? `var(--accent-2)` : active.isdescendant ? `var(--accent-1)` : `transparent`,
+        backgroundColor: active.isDirect ? `var(--accent-2)` : active.isDescendant ? `var(--accent-1)` : `transparent`,
         borderBottomRightRadius: `var(--radius-2)`,
         borderTopRightRadius: `var(--radius-2)`,
       }}

package/src/template/constants.ts

@@ -0,0 +1,17 @@
+/**
+ * Default Polen global data structure
+ * This ensures we always have a consistent shape for hydration
+ */
+export const DEFAULT_POLEN_DATA = {
+  serverContext: {
+    theme: 'light' as const,
+    isDev: false,
+  },
+} as const
+
+export type PolenGlobalData = {
+  serverContext: {
+    theme: 'light' | 'dark' | 'system'
+    isDev: boolean
+  }
+}

package/src/template/contexts/ThemeContext.tsx

@@ -1,51 +1,82 @@
 import type { React } from '#dep/react/index'
 import { createContext, useContext, useEffect, useState } from 'react'
+import * as Theme from '../../lib/theme/theme.js'
 
-type ThemeAppearance = 'light' | 'dark'
+type ThemeAppearance = `light` | `dark`
+type ThemePreference = `light` | `dark` | `system`
 
 interface ThemeContextValue {
   appearance: ThemeAppearance
+  preference: ThemePreference
   toggleTheme: () => void
 }
 
 const ThemeContext = createContext<ThemeContextValue | undefined>(undefined)
 
-const THEME_STORAGE_KEY = 'polen-theme-preference'
+// Create theme manager instance
+const themeManager = Theme.createThemeManager({
+  cookieName: `polen-theme-preference`,
+})
+
+// Theme CSS component to ensure consistent CSS on server and client
+const ThemeCSS: React.FC = () => {
+  const css = themeManager.getCSS()
+  return <style dangerouslySetInnerHTML={{ __html: css }} />
+}
 
 export const ThemeProvider: React.FC<{ children: React.ReactNode }> = ({ children }) => {
   const [appearance, setAppearance] = useState<ThemeAppearance>(() => {
-    // Check if we're in the browser
-    if (typeof window === 'undefined') {
-      return 'light'
-    }
-
-    // Check localStorage first
-    const stored = localStorage.getItem(THEME_STORAGE_KEY)
-    if (stored === 'light' || stored === 'dark') {
-      return stored
-    }
-
-    // Check system preference
-    if (window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches) {
-      return 'dark'
+    // Initial appearance from server or browser
+    const serverTheme = globalThis.__POLEN__.serverContext.theme
+    if (serverTheme === 'system') {
+      // During SSR, default to light for system preference
+      // Client will detect actual preference on mount
+      return typeof globalThis.window !== 'undefined'
+        ? (globalThis.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light')
+        : 'light'
     }
+    return serverTheme
+  })
 
-    return 'light'
+  const [preference, setPreference] = useState<ThemePreference>(() => {
+    // Initial preference from server-rendered theme
+    const serverTheme = globalThis.__POLEN__.serverContext.theme
+    // If server sent a specific theme (from cookie), use that as preference
+    // Otherwise it's system preference
+    return serverTheme
   })
 
   useEffect(() => {
-    // Persist to localStorage
-    if (typeof window !== 'undefined') {
-      localStorage.setItem(THEME_STORAGE_KEY, appearance)
+    // Apply theme preference to DOM on mount and when it changes
+    themeManager.applyToDOM(preference)
+
+    // Update appearance based on preference
+    if (preference === 'system') {
+      const systemTheme = globalThis.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light'
+      setAppearance(systemTheme)
+
+      // Listen for system theme changes
+      const mediaQuery = globalThis.matchMedia('(prefers-color-scheme: dark)')
+      const handleChange = (e: MediaQueryListEvent) => {
+        if (preference === 'system') {
+          setAppearance(e.matches ? 'dark' : 'light')
+        }
+      }
+      mediaQuery.addEventListener('change', handleChange)
+      return () => mediaQuery.removeEventListener('change', handleChange)
+    } else {
+      setAppearance(preference)
     }
-  }, [appearance])
+  }, [preference])
 
   const toggleTheme = () => {
-    setAppearance(prev => prev === 'light' ? 'dark' : 'light')
+    const newPref = themeManager.toggle() as ThemePreference
+    setPreference(newPref)
   }
 
   return (
-    <ThemeContext.Provider value={{ appearance, toggleTheme }}>
+    <ThemeContext.Provider value={{ appearance, preference, toggleTheme }}>
+      <ThemeCSS />
       {children}
     </ThemeContext.Provider>
   )
@@ -54,7 +85,7 @@ export const ThemeProvider: React.FC<{ children: React.ReactNode }> = ({ childre
 export const useTheme = () => {
   const context = useContext(ThemeContext)
   if (!context) {
-    throw new Error('useTheme must be used within a ThemeProvider')
+    throw new Error(`useTheme must be used within a ThemeProvider`)
   }
   return context
 }

package/src/template/entry.client.tsx

@@ -1,13 +1,9 @@
-// TODO it seems more logical to have this asset imported in the server entry.
-// But then, we won't get it from the client manifest. But we could get it from the server manifest. Should we do that?
-// But then, that wouldn't work for SPA. Does that matter? Just put a conditional here e.g. if (import.meta.env.PROD) ...?
 import '@radix-ui/themes/styles.css'
-// import './styles/code-block.css' // TODO: Handle CSS in build process
 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 { routes } from './routes.jsx'
+import { routes } from './routes.js'
 
 // SPA
 
@@ -24,8 +20,13 @@ const router = createBrowserRouter(routes, {
   basename: PROJECT_DATA.basePath === `/` ? undefined : PROJECT_DATA.basePath.slice(0, -1), // Remove trailing slash for React Router
 })
 
+const rootElement = document.getElementById(`app`)
+if (!rootElement) {
+  throw new Error(`Could not find app root element`)
+}
+
 ReactDomClient.hydrateRoot(
-  document,
+  rootElement,
   (
     <StrictMode>
       <RouterProvider router={router} />

package/src/template/global.d.ts

@@ -0,0 +1,7 @@
+import type { PolenGlobalData } from './constants'
+
+declare global {
+  var __POLEN__: PolenGlobalData
+}
+
+export {}

package/src/template/hooks/useClientOnly.ts

@@ -0,0 +1,21 @@
+import { useEffect, useState } from 'react'
+
+/**
+ * Hook that returns a server value during SSR and switches to client value after hydration
+ *
+ * @param clientValue - Function that returns the value to use on the client
+ * @param serverValue - Value to use during SSR
+ * @returns The appropriate value based on rendering context
+ */
+export function useClientOnly<T>(
+  clientValue: () => T,
+  serverValue: T,
+): T {
+  const [value, setValue] = useState<T>(serverValue)
+
+  useEffect(() => {
+    setValue(clientValue())
+  }, [])
+
+  return value
+}

package/src/template/hooks/useVersionPath.ts

@@ -0,0 +1,10 @@
+import { useParams } from 'react-router'
+
+/**
+ * Custom hook to generate version path for versioned routes
+ * Returns the appropriate path prefix for the current version
+ */
+export const useVersionPath = (): string => {
+  const params = useParams()
+  return params[`version`] ? `version/${params[`version`]}/` : ``
+}