polen 0.11.0-next.15 → 0.11.0-next.16

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

@@ -8,7 +8,19 @@ 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) => (
@@ -29,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} />
   }
@@ -50,7 +62,7 @@ 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)
@@ -86,7 +98,7 @@ const SBLink: React.FC<{
 //
 
 const Section: React.FC<{
-  section: Content.ItemSection
+  section: TemplateItemSection
 }> = ({ section }) => {
   return (
     <Box mt='8'>
@@ -109,7 +121,7 @@ const Section: React.FC<{
 //
 
 const LinkedSection: React.FC<{
-  section: Content.ItemSection
+  section: TemplateItemSection
 }> = ({ section }) => {
   return (
     <Box>
@@ -138,7 +150,7 @@ const LinkedSection: React.FC<{
   )
 }
 
-const SectionLink: React.FC<{ link: Content.ItemLink }> = ({ link }) => {
+const SectionLink: React.FC<{ link: TemplateItemLink }> = ({ link }) => {
   const location = useLocation()
   const { basePath } = useContext(SidebarContext)
   const href = Api.Schema.Routing.joinSegmentsAndPaths(basePath, link.pathExp)

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/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.json'
+import { templateConfig } from 'virtual:polen/project/config'
 import { routes } from './routes.js'
 
 // SPA
@@ -19,8 +19,8 @@ const router = createBrowserRouter(routes, {
   ...(window.__staticRouterHydrationData && {
     hydrationData: window.__staticRouterHydrationData,
   }),
-  ...(PROJECT_DATA.basePath !== '/' && {
-    basename: PROJECT_DATA.basePath.slice(0, -1), // Remove trailing slash for React Router
+  ...(templateConfig.build.base !== '/' && {
+    basename: templateConfig.build.base.slice(0, -1), // Remove trailing slash for React Router
   }),
 })
 

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,57 @@
+import type { HighlightedCode } from 'codehike/code'
+import { highlight } from 'codehike/code'
+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 highlightContent = async () => {
+      // Add a timeout to detect if highlight is hanging
+      const timeoutPromise = new Promise((_, reject) => {
+        setTimeout(() => reject(new Error('Highlight timeout after 5 seconds')), 5000)
+      })
+
+      const highlightPromise = highlight(
+        {
+          value: content,
+          lang: config.lang,
+          meta: metaString,
+        },
+        {
+          theme: 'github-light',
+        },
+      )
+
+      const highlighted = await Promise.race([highlightPromise, timeoutPromise])
+
+      setHighlightedCode(highlighted as any)
+    }
+    highlightContent()
+  }, [content, config.lang, config.interactive])
+
+  return highlightedCode
+}

package/src/template/layouts/SidebarLayout.tsx

@@ -1,14 +1,27 @@
 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'
 
+// 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
 }
@@ -25,16 +38,7 @@ export const SidebarLayout: React.FC<Props> = ({ children, sidebar, basePath, to
   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'>
@@ -53,24 +57,27 @@ export const SidebarLayout: React.FC<Props> = ({ children, sidebar, basePath, to
         </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}
-            {...(basePath !== undefined && { basePath })}
-            {...(topContent !== undefined && { topContent })}
-          />
-        </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/polen-url.ts

@@ -1,4 +1,4 @@
-import PROJECT_DATA from 'virtual:polen/project/data.json'
+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.json'
  * 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,
   )
 }

package/src/template/providers/mdx.tsx

@@ -0,0 +1,75 @@
+import { MDXProvider } from '@mdx-js/react'
+import {
+  Badge,
+  Box,
+  Button,
+  Callout,
+  Card,
+  Code,
+  DataList,
+  Em,
+  Heading,
+  Link,
+  Quote,
+  Separator,
+  Strong,
+  Table,
+  Tabs,
+  Text,
+  Tooltip,
+} from '@radix-ui/themes'
+import type { GraphQLSchema } from 'graphql'
+import type * as React from 'react'
+import { CodeBlock } from '../components/CodeBlock.js'
+
+interface MdxProviderProps extends React.PropsWithChildren {
+  schema?: GraphQLSchema | null
+}
+
+export const MdxProvider: React.FC<MdxProviderProps> = ({ children, schema }) => (
+  <MDXProvider
+    components={{
+      // Map markdown elements to Radix with spacing
+      p: (props) => <Text as='p' mb='4' {...props} />,
+      h1: (props) => <Heading size='8' mt='6' mb='4' {...props} />,
+      h2: (props) => <Heading size='7' mt='6' mb='3' {...props} />,
+      h3: (props) => <Heading size='6' mt='5' mb='3' {...props} />,
+      h4: (props) => <Heading size='5' mt='5' mb='2' {...props} />,
+      h5: (props) => <Heading size='4' mt='4' mb='2' {...props} />,
+      h6: (props) => <Heading size='3' mt='4' mb='2' {...props} />,
+      strong: Strong,
+      em: Em,
+      code: Code,
+      blockquote: (props) => <Quote my='4' {...props} />,
+      a: Link,
+      hr: (props) => <Separator my='6' {...props} />,
+      table: Table.Root,
+      thead: Table.Header,
+      tbody: Table.Body,
+      tr: Table.Row,
+      th: Table.ColumnHeaderCell,
+      td: Table.Cell,
+      // Lists need spacing too
+      ul: (props) => <Box as='ul' mb='4' style={{ paddingLeft: '1.5rem' }} {...props} />,
+      ol: (props) => <Box as='ol' mb='4' style={{ paddingLeft: '1.5rem' }} {...props} />,
+      li: (props) => <Box as='li' mb='2' {...props} />,
+
+      // Direct Radix components for MDX
+      Badge,
+      Button,
+      // @ts-expect-error
+      Callout,
+      Card,
+      // @ts-expect-error
+      DataList,
+      // @ts-expect-error
+      Tabs,
+      Tooltip,
+
+      // Code Hike component - schema will be loaded client-side if needed
+      CodeBlock: (props: any) => <CodeBlock {...props} schema={schema || undefined} />,
+    }}
+  >
+    {children}
+  </MDXProvider>
+)