polen 0.11.0-next.2 → 0.11.0-next.21

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

@@ -1,28 +1,51 @@
 import type { Content } from '#api/content/$'
+import type { React } from '#dep/react/index'
 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 {
-  data: Content.Item[]
+// Template layer extension: Allow React elements in title
+interface TemplateItemLink extends Omit<Content.ItemLink, 'title'> {
+  title: string | React.ReactNode
+}
+
+interface TemplateItemSection extends Omit<Content.ItemSection, 'title' | 'links'> {
+  title: string | React.ReactNode
+  links: TemplateItemLink[]
+}
+
+type TemplateItem = TemplateItemLink | TemplateItemSection
+
+interface Props extends LayoutProps, MarginProps, BoxOwnProps {
+  data: TemplateItem[]
+  basePath?: string
   style?: React.CSSProperties
+  topContent?: React.ReactNode
 }
 
-export const Sidebar = ({ data, ...props }: SidebarProps) => {
+export const Sidebar = ({ data, basePath, topContent, ...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 !== undefined ? { basePath } : {}}>
+      <Box
+        data-testid='sidebar'
+        role='Sidebar'
+        {...props}
+      >
+        <style>
+          {`
+            div[role="Sidebar"] a:not([data-active]):hover {
+              background-color: var(--iris-2) !important;
+            }
+          `}
+        </style>
+        {topContent && (
+          <Box mb='4'>
+            {topContent}
+          </Box>
+        )}
+        <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,11 +1,26 @@
 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 }) => {
+// Template layer extension: Allow React elements in title
+interface TemplateItemLink extends Omit<Content.ItemLink, 'title'> {
+  title: string | React.ReactNode
+}
+
+interface TemplateItemSection extends Omit<Content.ItemSection, 'title' | 'links'> {
+  title: string | React.ReactNode
+  links: TemplateItemLink[]
+}
+
+type TemplateItem = TemplateItemLink | TemplateItemSection
+
+export const Items: React.FC<{ items: TemplateItem[] }> = ({ items }) => {
   return (
     <Flex direction='column' gap='2px'>
       {items.map((item, index) => (
@@ -26,7 +41,7 @@ export const Items: React.FC<{ items: Content.Item[] }> = ({ items }) => {
 //
 //
 
-export const Item: React.FC<{ item: Content.Item }> = ({ item }) => {
+export const Item: React.FC<{ item: TemplateItem }> = ({ item }) => {
   if (item.type === `ItemLink`) {
     return <SBLink link={item} />
   }
@@ -47,18 +62,20 @@ export const Item: React.FC<{ item: Content.Item }> = ({ item }) => {
 //
 
 const SBLink: React.FC<{
-  link: Content.ItemLink | Content.ItemSection
+  link: TemplateItemLink | TemplateItemSection
 }> = ({ 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`,
@@ -81,7 +98,7 @@ const SBLink: React.FC<{
 //
 
 const Section: React.FC<{
-  section: Content.ItemSection
+  section: TemplateItemSection
 }> = ({ section }) => {
   return (
     <Box mt='8'>
@@ -104,7 +121,7 @@ const Section: React.FC<{
 //
 
 const LinkedSection: React.FC<{
-  section: Content.ItemSection
+  section: TemplateItemSection
 }> = ({ section }) => {
   return (
     <Box>
@@ -133,14 +150,16 @@ const LinkedSection: React.FC<{
   )
 }
 
-const SectionLink: React.FC<{ link: Content.ItemLink }> = ({ link }) => {
+const SectionLink: React.FC<{ link: TemplateItemLink }> = ({ 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/components/swiss/SwissHeading.tsx

@@ -0,0 +1,44 @@
+import { Heading } from '@radix-ui/themes'
+import * as React from 'react'
+
+/**
+ * Swiss Heading Component
+ *
+ * A sharp, impactful heading component that splits words for vertical stacking.
+ * Features extreme typography contrast and tight tracking.
+ */
+export const SwissHeading: React.FC<React.ComponentProps<typeof Heading>> = ({
+  children,
+  ...props
+}) => {
+  // Split words for stacked display
+  const words = typeof children === 'string'
+    ? children.split(' ')
+    : React.Children.toArray(children)
+
+  return (
+    <Heading
+      {...props}
+      weight='bold'
+      style={{
+        fontSize: 'clamp(2.5rem, 7vw, 5.5rem)',
+        lineHeight: 1.1,
+        letterSpacing: '-0.02em',
+        fontWeight: 900,
+        ...props.style,
+      }}
+    >
+      {words.map((word, i) => (
+        <span
+          key={i}
+          style={{
+            display: 'block',
+            marginBottom: i < words.length - 1 ? '0.05em' : 0,
+          }}
+        >
+          {word}
+        </span>
+      ))}
+    </Heading>
+  )
+}

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

@@ -0,0 +1 @@
+export { SwissHeading } from './SwissHeading.js'

package/src/template/contexts/GraphqlLifecycleContext.tsx

@@ -0,0 +1,43 @@
+import type { React } from '#dep/react/index'
+import { Lifecycles } from '#lib/lifecycles/$'
+import { Schema } from '#lib/schema/$'
+import { createContext, useContext } from 'react'
+
+interface SchemaContextValue {
+  schema: Schema.Schema
+  lifecycles: Lifecycles.Lifecycles
+}
+
+const SchemaContext = createContext<SchemaContextValue | undefined>(undefined)
+
+export const GraphqlLifecycleProvider: React.FC<{
+  children: React.ReactNode
+  lifecycle: Lifecycles.Lifecycles
+  schema: Schema.Schema
+}> = ({ children, lifecycle, schema }) => {
+  return (
+    <SchemaContext.Provider value={{ schema, lifecycles: lifecycle }}>
+      {children}
+    </SchemaContext.Provider>
+  )
+}
+
+export const useGraphqlLifecycle = () => {
+  const context = useContext(SchemaContext)
+  if (!context) {
+    throw new Error(`useGraphqlLifecycle must be used within a GraphqlLifecycleProvider`)
+  }
+  // Maintain backward compatibility
+  return {
+    lifecycle: context.lifecycles,
+    currentVersion: Schema.getVersion(context.schema),
+  }
+}
+
+export const useSchema = () => {
+  const context = useContext(SchemaContext)
+  if (!context) {
+    throw new Error(`useSchema must be used within a GraphqlLifecycleProvider`)
+  }
+  return context
+}

package/src/template/contexts/ThemeContext.tsx

@@ -27,7 +27,7 @@ const ThemeCSS: React.FC = () => {
 export const ThemeProvider: React.FC<{ children: React.ReactNode }> = ({ children }) => {
   const [appearance, setAppearance] = useState<ThemeAppearance>(() => {
     // Initial appearance from server or browser
-    const serverTheme = globalThis.__POLEN__.serverContext.theme
+    const serverTheme = (globalThis as any).__POLEN__.serverContext.theme
     if (serverTheme === 'system') {
       // During SSR, default to light for system preference
       // Client will detect actual preference on mount
@@ -40,7 +40,7 @@ export const ThemeProvider: React.FC<{ children: React.ReactNode }> = ({ childre
 
   const [preference, setPreference] = useState<ThemePreference>(() => {
     // Initial preference from server-rendered theme
-    const serverTheme = globalThis.__POLEN__.serverContext.theme
+    const serverTheme = (globalThis as any).__POLEN__.serverContext.theme
     // If server sent a specific theme (from cookie), use that as preference
     // Otherwise it's system preference
     return serverTheme

package/src/template/entry.client.tsx

@@ -2,7 +2,7 @@ import '@radix-ui/themes/styles.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 { templateConfig } from 'virtual:polen/project/config'
 import { routes } from './routes.js'
 
 // SPA
@@ -16,8 +16,12 @@ import { routes } from './routes.js'
 // SSR
 
 const router = createBrowserRouter(routes, {
-  hydrationData: window.__staticRouterHydrationData,
-  basename: PROJECT_DATA.basePath === `/` ? undefined : PROJECT_DATA.basePath.slice(0, -1), // Remove trailing slash for React Router
+  ...(window.__staticRouterHydrationData && {
+    hydrationData: window.__staticRouterHydrationData,
+  }),
+  ...(templateConfig.build.base !== '/' && {
+    basename: templateConfig.build.base.slice(0, -1), // Remove trailing slash for React Router
+  }),
 })
 
 const rootElement = document.getElementById(`app`)

package/src/template/env.d.ts

@@ -0,0 +1,3 @@
+/// <reference types="vite/client" />
+/// <reference path="../types/virtual-modules.d.ts" />
+/// <reference path="../types/global-constants.d.ts" />

package/src/template/hooks/use-examples.ts

@@ -0,0 +1,46 @@
+import type { Example } from '#api/examples/schemas/example/example'
+import type { ExampleReference, TypeUsageIndex } from '#api/examples/schemas/type-usage-index'
+import { getExampleReferencesForType } from '#api/examples/type-usage-indexer'
+import { Version } from '#lib/version/$'
+import { HashSet } from 'effect'
+import { useMemo } from 'react'
+import { examplesCatalog } from 'virtual:polen/project/examples'
+
+/**
+ * Hook to access the full examples catalog.
+ */
+export const useExamples = () => {
+  return examplesCatalog
+}
+
+/**
+ * Hook to get example references that use a specific GraphQL type.
+ *
+ * @param typeName - The name of the GraphQL type
+ * @param version - Optional version to filter by (null for unversioned)
+ * @returns HashSet of example references that use the specified type
+ */
+export const useExamplesForType = (
+  typeName: string,
+  version: Version.Version | null = null,
+): HashSet.HashSet<ExampleReference> => {
+  // The typeUsageIndex is already a HashMap thanks to the schema transformation
+  const typeUsageIndex = examplesCatalog?.typeUsageIndex as TypeUsageIndex | undefined
+
+  // Memoize the filtered example references
+  return useMemo(() => {
+    if (!typeUsageIndex) {
+      return HashSet.empty<ExampleReference>()
+    }
+
+    // Get example references for this type and return them directly
+    return getExampleReferencesForType(typeUsageIndex, typeName, version)
+  }, [typeUsageIndex, typeName, version])
+}
+
+/**
+ * Hook to check if any examples exist.
+ */
+export const useHasExamples = (): boolean => {
+  return examplesCatalog?.examples?.length > 0
+}

package/src/template/hooks/use-highlighted.ts

@@ -0,0 +1,69 @@
+import type { HighlightedCode } from 'codehike/code'
+import { highlight } from 'codehike/code'
+import { Duration, Effect } from 'effect'
+import * as React from 'react'
+
+/**
+ * Hook to asynchronously highlight code content using CodeHike.
+ *
+ * @param content - The code content to highlight
+ * @param lang - The language for syntax highlighting (default: 'graphql')
+ * @param interactive - Whether to add interactive meta flag (default: false)
+ * @returns The highlighted code object or null while loading
+ */
+export const useHighlighted = (
+  content: string,
+  options?: {
+    lang?: string
+    interactive?: boolean
+  },
+): HighlightedCode | null => {
+  const config = {
+    interactive: options?.interactive ?? false,
+    lang: options?.lang ?? 'graphql',
+  }
+
+  const meta = []
+  if (config.interactive) meta.push('interactive')
+  const metaString = meta.join(' ')
+
+  const [highlightedCode, setHighlightedCode] = React.useState<HighlightedCode | null>(null)
+
+  React.useEffect(() => {
+    const HIGHLIGHT_TIMEOUT = Duration.seconds(5)
+
+    const highlightContent = async () => {
+      try {
+        const highlighted = await Effect.runPromise(
+          Effect.tryPromise({
+            try: () =>
+              highlight(
+                {
+                  value: content,
+                  lang: config.lang,
+                  meta: metaString,
+                },
+                {
+                  theme: 'github-light',
+                },
+              ),
+            catch: (error) => new Error(`Highlight failed: ${error}`),
+          }).pipe(
+            Effect.timeout(HIGHLIGHT_TIMEOUT),
+            Effect.catchTag(
+              'TimeoutException',
+              () => Effect.fail(new Error(`Highlight timeout after ${Duration.toSeconds(HIGHLIGHT_TIMEOUT)} seconds`)),
+            ),
+          ),
+        )
+        setHighlightedCode(highlighted)
+      } catch (error) {
+        console.error('Failed to highlight code:', error)
+        setHighlightedCode(null)
+      }
+    }
+    highlightContent()
+  }, [content, config.lang, config.interactive])
+
+  return highlightedCode
+}

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,5 @@
+import { Api } from '#api/iso'
+import { Version } from '#lib/version/$'
 import { useParams } from 'react-router'
 
 /**
@@ -6,5 +8,10 @@ import { useParams } from 'react-router'
  */
 export const useVersionPath = (): string => {
   const params = useParams()
-  return params[`version`] ? `version/${params[`version`]}/` : ``
+  const versionParam = params[`version`]
+  if (!versionParam) {
+    return ''
+  }
+  const version = Version.fromString(versionParam)
+  return Api.Schema.Routing.createReferenceVersionPath(version)
 }

package/src/template/layouts/SidebarLayout.tsx

@@ -1,17 +1,32 @@
 import type { Content } from '#api/content/$'
-import { Box, Grid } from '@radix-ui/themes'
+import { Swiss } from '#lib/swiss'
+import { Box } 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 {
+// Template layer extension: Allow React elements in title
+interface TemplateItemLink extends Omit<Content.ItemLink, 'title'> {
+  title: string | React.ReactNode
+}
+
+interface TemplateItemSection extends Omit<Content.ItemSection, 'title' | 'links'> {
+  title: string | React.ReactNode
+  links: TemplateItemLink[]
+}
+
+type TemplateItem = TemplateItemLink | TemplateItemSection
+
+interface Props {
   children: React.ReactNode
-  sidebar: Content.Item[]
+  sidebar: TemplateItem[]
+  basePath?: string
+  topContent?: React.ReactNode
 }
 
-export const SidebarLayout: React.FC<SidebarLayoutProps> = ({ children, sidebar }) => {
+export const SidebarLayout: React.FC<Props> = ({ children, sidebar, basePath, topContent }) => {
   const location = useLocation()
   const [mobileMenuOpen, setMobileMenuOpen] = useState(false)
 
@@ -23,16 +38,7 @@ export const SidebarLayout: React.FC<SidebarLayoutProps> = ({ children, sidebar
   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` }}
-    >
+    <Swiss.Body subgrid>
       {/* Mobile menu - only show when sidebar exists */}
       {isShowSidebar && (
         <Box display={{ initial: `block`, md: `none` }} mb='4'>
@@ -45,24 +51,33 @@ export const SidebarLayout: React.FC<SidebarLayoutProps> = ({ children, sidebar
               setMobileMenuOpen(false)
             }}
             sidebarData={sidebar}
+            {...(basePath !== undefined && { basePath })}
+            {...(topContent !== undefined && { topContent })}
           />
         </Box>
       )}
 
-      {/* Desktop Sidebar */}
+      {/* Desktop Sidebar - 3 columns */}
       {isShowSidebar && (
-        <Box
-          display={{ initial: `none`, xs: `none`, sm: `none`, md: `block` }}
-          gridColumn='1 / 3'
-          gridRow='1 / auto'
-        >
-          <Sidebar data={sidebar} />
-        </Box>
+        <Swiss.Item cols={{ initial: 3, md: 3 }}>
+          <Box
+            display={{ initial: `none`, md: `block` }}
+            position={'sticky'}
+            top={'4'}
+          >
+            <Sidebar
+              data={sidebar}
+              {...(basePath !== undefined && { basePath })}
+              {...(topContent !== undefined && { topContent })}
+            />
+          </Box>
+        </Swiss.Item>
       )}
 
-      <Box gridArea='content / content / auto / 8'>
+      {/* Main Content - 8 columns on mobile, 9 on desktop when sidebar exists, 12 when not */}
+      <Swiss.Item cols={8} start={5}>
         {children}
-      </Box>
-    </Grid>
+      </Swiss.Item>
+    </Swiss.Body>
   )
 }

package/src/template/layouts/index.ts

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

package/src/template/lib/fetch-text.ts

@@ -1,13 +1,54 @@
+import { Either } from 'effect'
+
+/**
+ * Error type for fetch failures
+ */
+export interface FetchError {
+  readonly _tag: 'FetchError'
+  readonly url: string
+  readonly status: number
+  readonly statusText: string
+  readonly message: string
+}
+
+const makeFetchError = (url: string, status: number, statusText: string): FetchError => ({
+  _tag: 'FetchError',
+  url,
+  status,
+  statusText,
+  message: `Failed to fetch: ${url} (${status} ${statusText})`,
+})
+
 /**
  * Fetch text content from a URL
  * @param url - The URL to fetch from
+ * @returns Either with text content on right or FetchError on left
+ */
+export const fetchTextEither = async (url: string): Promise<Either.Either<string, FetchError>> => {
+  try {
+    const response = await fetch(url)
+    if (!response.ok) {
+      return Either.left(makeFetchError(url, response.status, response.statusText))
+    }
+    const text = await response.text()
+    return Either.right(text)
+  } catch (error) {
+    // Network errors or other exceptions
+    return Either.left(makeFetchError(url, 0, 'Network Error'))
+  }
+}
+
+/**
+ * Fetch text content from a URL (legacy throwing version)
+ * @param url - The URL to fetch from
  * @returns Promise that resolves to the text content
  * @throws Error if the request fails
+ * @deprecated Use fetchTextEither for better error handling
  */
 export const fetchText = async (url: string): Promise<string> => {
-  const response = await fetch(url)
-  if (!response.ok) {
-    throw new Error(`Failed to fetch: ${url} (${response.status} ${response.statusText})`)
+  const result = await fetchTextEither(url)
+  if (Either.isLeft(result)) {
+    throw new Error(result.left.message)
   }
-  return response.text()
+  return result.right
 }

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

@@ -1,4 +1,4 @@
-import PROJECT_DATA from 'virtual:polen/project/data.jsonsuper'
+import { templateConfig } from 'virtual:polen/project/config'
 
 /**
  * Create a Polen URL path that respects the configured base path for UI navigation.
@@ -23,7 +23,7 @@ import PROJECT_DATA from 'virtual:polen/project/data.jsonsuper'
  * polenUrlPath('reference/Pokemon#field') // '/demos/pokemon/reference/Pokemon#field'
  */
 export const polenUrlPath = (...segments: string[]): string => {
-  const basePath = PROJECT_DATA.basePath // e.g., '/demos/pokemon/'
+  const basePath = templateConfig.build.base // e.g., '/demos/pokemon/'
 
   // Join segments and normalize slashes
   const path = segments
@@ -49,7 +49,7 @@ export const polenUrlPath = (...segments: string[]): string => {
  */
 export const polenUrlPathAssets = (...segments: string[]): string => {
   return polenUrlPath(
-    PROJECT_DATA.server.routes.assets,
+    templateConfig.server.routes.assets,
     ...segments,
   )
 }