polen 0.10.0-next.13 → 0.10.0-next.15

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.tsx'
+import { Link } from './Link.js'
 
 export interface Props {
   type: GraphQLType // Can be either GraphQLInputType or GraphQLOutputType

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.tsx'
+import { Link } from './Link.js'
 
 export interface Props {
   type: GraphQLObjectType | GraphQLInterfaceType

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.tsx'
+import { Link } from './Link.js'
 
 export interface Props {
   schema: GraphQLSchema

package/src/template/components/content/$$.ts

@@ -1,2 +1,2 @@
 export { Callout, Tabs } from '@radix-ui/themes'
-export { GraphQLDocumentWithSchema } from './GraphQLDocumentWithSchema.tsx'
+export { GraphQLDocumentWithSchema } from './GraphQLDocumentWithSchema.js'

package/src/template/components/content/GraphQLDocumentWithSchema.tsx

@@ -1,18 +1,13 @@
-import type { GraphQLSchema } from 'graphql'
 import React from 'react'
 import PROJECT_DATA from 'virtual:polen/project/data.jsonsuper'
-import { GraphQLDocument } from '../../../lib/graphql-document/components/GraphQLDocument.tsx'
-import type { GraphQLDocumentProps } from '../../../lib/graphql-document/components/GraphQLDocument.tsx'
+import { GraphQLDocument } from '../../../lib/graphql-document/components/GraphQLDocument.js'
+import type { GraphQLDocumentProps } from '../../../lib/graphql-document/components/GraphQLDocument.js'
 
 /**
  * Wrapper component that provides schema from virtual module directly to GraphQLDocument
  * This bypasses the context issue with MDX components
  */
-export const GraphQLDocumentWithSchema: React.FC<Omit<GraphQLDocumentProps, 'schema'>> = (props) => {
+export const GraphQLDocumentWithSchema: React.FC<Omit<GraphQLDocumentProps, `schema`>> = (props) => {
   const schema = PROJECT_DATA.schema?.versions[0]?.after
-  console.log('Template wrapper - schema:', schema ? 'EXISTS' : 'UNDEFINED')
-  console.log('Template wrapper - props:', props)
-  console.log('Template wrapper - PROJECT_DATA.schema:', PROJECT_DATA.schema)
-
   return <GraphQLDocument {...props} schema={schema} />
 }

package/src/template/components/content/GraphQLDocumentWrapper.tsx

@@ -1,52 +1,37 @@
 import React from 'react'
-import { useNavigate } from 'react-router'
-import { GraphQLDocument } from '../../../lib/graphql-document/components/GraphQLDocument.tsx'
-import type { GraphQLDocumentProps } from '../../../lib/graphql-document/components/GraphQLDocument.tsx'
-import { highlightCode } from '../../../lib/shiki/shiki.ts'
+import { GraphQLDocument } from '../../../lib/graphql-document/components/GraphQLDocument.js'
+import type { GraphQLDocumentProps } from '../../../lib/graphql-document/components/GraphQLDocument.js'
 
 /**
  * Client-side wrapper that hydrates GraphQL documents with schema
  */
-export const GraphQLDocumentWithSchema: React.FC<Omit<GraphQLDocumentProps, 'schema'>> = (props) => {
+export const GraphQLDocumentWithSchema: React.FC<Omit<GraphQLDocumentProps, `schema`>> = (props) => {
   try {
     const [schema, setSchema] = React.useState<any>(null)
     const [isClient, setIsClient] = React.useState(false)
-    const [highlightedHtml, setHighlightedHtml] = React.useState<string | null>(null)
 
     React.useEffect(() => {
       setIsClient(true)
 
-      // Highlight the code
-      if (typeof props.children === 'string') {
-        highlightCode({
-          code: props.children,
-          lang: 'graphql',
-          theme: 'light', // You can make this dynamic based on theme
-        }).then(html => {
-          setHighlightedHtml(html)
-        }).catch(err => {
-          console.error('Failed to highlight code:', err)
-        })
-      }
-
       // Access virtual module only on client side
-      if (typeof window !== 'undefined') {
-        import('virtual:polen/project/data.jsonsuper').then(PROJECT_DATA => {
+      if (typeof window !== `undefined`) {
+        import(`virtual:polen/project/data.jsonsuper`).then(PROJECT_DATA => {
           const s = PROJECT_DATA.default?.schema?.versions?.[0]?.after
+          // Schema loaded successfully
           if (s) {
             setSchema(s)
           }
-        }).catch(err => {
-          console.error('Failed to load schema:', err)
+        }).catch(() => {
+          // Schema loading is optional - continue without it
         })
       }
-    }, [props.children])
+    }, [])
 
     // During SSR, render a simple code block
     if (!isClient) {
       return (
         <div data-testid='graphql-document' className='graphql-document graphql-document-static'>
-          <pre className='shiki shiki-themes github-light tokyo-night'>
+          <pre>
             <code className="language-graphql">{props.children}</code>
           </pre>
         </div>
@@ -56,7 +41,7 @@ export const GraphQLDocumentWithSchema: React.FC<Omit<GraphQLDocumentProps, 'sch
     // During client render, use the full component
     // Pass a custom navigate function that doesn't require router
     const handleNavigate = (url: string) => {
-      if (typeof window !== 'undefined') {
+      if (typeof window !== `undefined`) {
         window.location.href = url
       }
     }
@@ -66,17 +51,22 @@ export const GraphQLDocumentWithSchema: React.FC<Omit<GraphQLDocumentProps, 'sch
         <GraphQLDocument
           {...props}
           schema={schema}
-          highlightedHtml={highlightedHtml || undefined}
           options={{
+            debug: false, // Default to false for shipping
             ...props.options,
             onNavigate: handleNavigate,
-            debug: false, // Disable debug mode for shipping
           }}
         />
       </div>
     )
   } catch (err) {
-    console.error('GraphQLDocumentWithSchema error:', err)
-    return <div>Error rendering GraphQL document</div>
+    // Fall back to plain code block on error
+    return (
+      <div data-testid='graphql-document' className='graphql-document graphql-document-static'>
+        <pre>
+          <code className="language-graphql">{props.children}</code>
+        </pre>
+      </div>
+    )
   }
 }

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

@@ -1,2 +1,2 @@
-export * from './type-kind-icon.tsx'
-export * from './type-link.tsx'
+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.tsx'
+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,8 +1,8 @@
 import { Grafaid } from '#lib/grafaid/index'
 import { Code, Flex } from '@radix-ui/themes'
-import { Link } from '../Link.tsx'
-import { TypeKindIcon } from './graphql.tsx'
-import { typeKindTokensIndex } from './type-kind-tokens.ts'
+import { Link } from '../Link.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)

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,7 +3,7 @@ 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 (
@@ -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'
@@ -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,10 @@
-// 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'
 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.tsx'
+import { routes } from './routes.js'
 
 // SPA
 
@@ -24,8 +21,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/routes/changelog.tsx

@@ -1,7 +1,7 @@
 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.tsx'
+import { Changelog } from '../components/Changelog.js'
 
 const loader = createLoader(() => {
   return {

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.tsx'
-import { MissingSchema } from '../components/MissingSchema.tsx'
-import type { reference } from './reference.tsx'
+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 }

package/src/template/routes/reference.$type.tsx

@@ -1,9 +1,9 @@
 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.tsx'
-import { NamedType } from '../components/NamedType.tsx'
-import type { reference } from './reference.tsx'
+import { MissingSchema } from '../components/MissingSchema.js'
+import { NamedType } from '../components/NamedType.js'
+import type { reference } from './reference.js'
 
 const Component = () => {
   const params = useParams() as { type: string }

package/src/template/routes/reference.tsx

@@ -3,8 +3,8 @@ import { createLoader, useLoaderData } from '#lib/react-router-loader/react-rout
 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.tsx'
-import { reference$type } from './reference.$type.tsx'
+import { MissingSchema } from '../components/MissingSchema.js'
+import { reference$type } from './reference.$type.js'
 
 const loader = createLoader(() => {
   const latestSchemaVersion = PROJECT_DATA.schema?.versions[0].after ?? null