polen 0.10.0-next.8 → 0.10.0

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

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,8 +1,8 @@
 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 { 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,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/layouts/SidebarLayout.tsx

@@ -0,0 +1,68 @@
+import type { Content } from '#api/content/$'
+import { Box, Grid } from '@radix-ui/themes'
+import type React from 'react'
+import { useEffect, useState } from 'react'
+import { useLocation } from 'react-router'
+import { HamburgerMenu } from '../components/HamburgerMenu.js'
+import { Sidebar } from '../components/sidebar/Sidebar.js'
+
+interface SidebarLayoutProps {
+  children: React.ReactNode
+  sidebar: Content.Item[]
+}
+
+export const SidebarLayout: React.FC<SidebarLayoutProps> = ({ children, sidebar }) => {
+  const location = useLocation()
+  const [mobileMenuOpen, setMobileMenuOpen] = useState(false)
+
+  // Close mobile menu on route change
+  useEffect(() => {
+    setMobileMenuOpen(false)
+  }, [location.pathname])
+
+  const isShowSidebar = sidebar && sidebar.length > 0
+
+  return (
+    <Grid
+      areas={{
+        initial: `'content'`,
+        sm: `'content'`,
+        md: `'sidebar sidebar . content content content content content'`,
+      }}
+      rows='auto'
+      columns={{ initial: `1fr`, sm: `1fr`, md: `repeat(8, 1fr)` }}
+      gapX={{ initial: `0`, sm: `0`, md: `2` }}
+    >
+      {/* Mobile menu - only show when sidebar exists */}
+      {isShowSidebar && (
+        <Box display={{ initial: `block`, md: `none` }} mb='4'>
+          <HamburgerMenu
+            isOpen={mobileMenuOpen}
+            onToggle={() => {
+              setMobileMenuOpen(!mobileMenuOpen)
+            }}
+            onClose={() => {
+              setMobileMenuOpen(false)
+            }}
+            sidebarData={sidebar}
+          />
+        </Box>
+      )}
+
+      {/* Desktop Sidebar */}
+      {isShowSidebar && (
+        <Box
+          display={{ initial: `none`, xs: `none`, sm: `none`, md: `block` }}
+          gridColumn='1 / 3'
+          gridRow='1 / auto'
+        >
+          <Sidebar data={sidebar} />
+        </Box>
+      )}
+
+      <Box gridArea='content / content / auto / 8'>
+        {children}
+      </Box>
+    </Grid>
+  )
+}

package/src/template/layouts/index.ts

@@ -0,0 +1 @@
+export * from './SidebarLayout.js'

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

@@ -0,0 +1,35 @@
+import PROJECT_DATA from 'virtual:polen/project/data.jsonsuper'
+
+/**
+ * Create a Polen URL path that respects the configured base path for UI navigation.
+ *
+ * **Warning:** When using this with raw `<a>` tags instead of React Router's Link component,
+ * you lose the following benefits:
+ * - Client-side navigation (faster, no page refresh)
+ * - Browser history management and back/forward optimization
+ * - Scroll position restoration
+ * - Route preloading and prefetching
+ * - Consistent navigation state management
+ * - Better accessibility features (screen reader announcements)
+ *
+ * Consider using React Router's `Link` component with `to={polenUrlPath(...)}` for better UX.
+ *
+ * @param segments - Path segments to join (e.g., 'reference', 'Pokemon')
+ * @returns Full URL path with base path (e.g., '/demos/pokemon/reference/Pokemon')
+ *
+ * @example
+ * polenUrlPath('reference', 'Pokemon') // '/demos/pokemon/reference/Pokemon'
+ * polenUrlPath('/reference/Pokemon') // '/demos/pokemon/reference/Pokemon'
+ * polenUrlPath('reference/Pokemon#field') // '/demos/pokemon/reference/Pokemon#field'
+ */
+export const polenUrlPath = (...segments: string[]): string => {
+  const basePath = PROJECT_DATA.basePath // e.g., '/demos/pokemon/'
+
+  // Join segments and normalize slashes
+  const path = segments
+    .join('/')
+    .replace(/\/+/g, '/') // Remove duplicate slashes
+    .replace(/^\//, '') // Remove leading slash
+
+  return basePath + path
+}

package/src/template/routes/changelog.tsx

@@ -1,7 +1,8 @@
 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.jsx'
+import { Changelog } from '../components/Changelog.js'
+import { ChangelogLayout } from '../components/ChangelogLayout.js'
 
 const loader = createLoader(() => {
   return {
@@ -16,7 +17,11 @@ const Component = () => {
     return <div>No data to show. There is no schema is.</div>
   }
 
-  return <Changelog schema={data.schema} />
+  return (
+    <ChangelogLayout versions={data.schema.versions}>
+      <Changelog schema={data.schema} />
+    </ChangelogLayout>
+  )
 }
 
 export const changelog = createRoute({

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

@@ -1,11 +1,12 @@
+import type { Content } from '#api/content/$'
+import { GrafaidOld } from '#lib/grafaid-old/index'
 import { createRoute } from '#lib/react-router-aid/react-router-aid'
 import { createLoader, useLoaderData } from '#lib/react-router-loader/react-router-loader'
-import { Container, Flex } from '@radix-ui/themes'
 import { Outlet } from 'react-router'
 import PROJECT_DATA from 'virtual:polen/project/data.jsonsuper'
-import { MissingSchema } from '../components/MissingSchema.jsx'
-import { TypeIndex } from '../components/TypeIndex.jsx'
-import { reference$type } from './reference.$type.jsx'
+import { MissingSchema } from '../components/MissingSchema.js'
+import { SidebarLayout } from '../layouts/index.js'
+import { reference$type } from './reference.$type.js'
 
 const loader = createLoader(() => {
   const latestSchemaVersion = PROJECT_DATA.schema?.versions[0].after ?? null
@@ -21,13 +22,30 @@ const Component = () => {
     return <MissingSchema />
   }
 
+  // Build reference sidebar from schema types
+  const kindMap = GrafaidOld.getKindMap(data.schema)
+
+  const sidebarItems: Content.Item[] = []
+  const kindEntries = Object.entries(kindMap.list).filter(([_, types]) => types.length > 0)
+
+  for (const [title, types] of kindEntries) {
+    sidebarItems.push({
+      type: `ItemSection` as const,
+      title,
+      pathExp: `reference-${title.toLowerCase()}`,
+      isLinkToo: false,
+      links: types.map(type => ({
+        type: `ItemLink` as const,
+        title: type.name,
+        pathExp: `reference/${type.name}`,
+      })),
+    })
+  }
+
   return (
-    <Flex direction='row' align='start'>
-      <TypeIndex schema={data.schema} />
-      <Container>
-        <Outlet />
-      </Container>
-    </Flex>
+    <SidebarLayout sidebar={sidebarItems}>
+      <Outlet />
+    </SidebarLayout>
   )
 }