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

package/src/template/components/GraphQLInteractive/lib/parser.ts

@@ -5,7 +5,9 @@
  * analysis to create unified tokens for interactive code blocks.
  */
 
+import { Api } from '#api/iso'
 import type { CodeAnnotation } from 'codehike/code'
+import { Either } from 'effect'
 import {
   getNamedType,
   type GraphQLArgument,
@@ -14,7 +16,6 @@ import {
   GraphQLInputObjectType,
   GraphQLInterfaceType,
   GraphQLObjectType,
-  type GraphQLOutputType,
   GraphQLScalarType,
   type GraphQLSchema,
   GraphQLUnionType,
@@ -24,12 +25,7 @@ import {
 import graphqlWasmUrl from 'tree-sitter-graphql-grammar-wasm/grammar.wasm?url'
 import * as WebTreeSitter from 'web-tree-sitter'
 import treeSitterWasmUrl from 'web-tree-sitter/tree-sitter.wasm?url'
-import {
-  isKeywordNodeType,
-  isLiteralNodeType,
-  isPunctuationNodeType,
-  type TreeSitterGraphQLNodeType,
-} from './graphql-node-types.js'
+import { isKeywordNodeType, isPunctuationNodeType, type TreeSitterGraphQLNodeType } from './graphql-node-types.js'
 import type { SemanticNode } from './semantic-nodes.js'
 import {
   isArgument,
@@ -68,7 +64,7 @@ export interface GraphQLToken {
    * Optional semantic information from GraphQL schema analysis
    * This includes type information, field definitions, and validation results
    */
-  semantic?: SemanticNode
+  semantic: SemanticNode | undefined
 
   /** Text content of the token (computed from tree-sitter node) */
   get text(): string
@@ -263,42 +259,63 @@ class UnifiedToken implements GraphQLToken {
 
     // Arguments - use #<field>__<argument> pattern
     if (isArgument(this.semantic)) {
-      return `/reference/${this.semantic.parentType.name}#${this.semantic.parentField.name}__${this.semantic.argumentDef.name}`
+      const basePath = Api.Schema.Routing.createReferencePath({
+        type: this.semantic.parentType.name,
+      })
+      return `${basePath}#${this.semantic.parentField.name}__${this.semantic.argumentDef.name}`
     }
 
     // Output fields - use hash links since field routes aren't connected yet
     if (isOutputField(this.semantic)) {
-      return `/reference/${this.semantic.parentType.name}#${this.semantic.fieldDef.name}`
+      const basePath = Api.Schema.Routing.createReferencePath({
+        type: this.semantic.parentType.name,
+      })
+      return `${basePath}#${this.semantic.fieldDef.name}`
     }
 
     // Input fields - use hash links since field routes aren't connected yet
     if (isInputField(this.semantic)) {
-      return `/reference/${this.semantic.parentType.name}#${this.semantic.fieldDef.name}`
+      const basePath = Api.Schema.Routing.createReferencePath({
+        type: this.semantic.parentType.name,
+      })
+      return `${basePath}#${this.semantic.fieldDef.name}`
     }
 
     // Type references - use :type pattern
     if (this.semantic instanceof GraphQLObjectType) {
-      return `/reference/${this.semantic.name}`
+      return Api.Schema.Routing.createReferencePath({
+        type: this.semantic.name,
+      })
     }
 
     if (this.semantic instanceof GraphQLScalarType) {
-      return `/reference/${this.semantic.name}`
+      return Api.Schema.Routing.createReferencePath({
+        type: this.semantic.name,
+      })
     }
 
     if (this.semantic instanceof GraphQLInterfaceType) {
-      return `/reference/${this.semantic.name}`
+      return Api.Schema.Routing.createReferencePath({
+        type: this.semantic.name,
+      })
     }
 
     if (this.semantic instanceof GraphQLUnionType) {
-      return `/reference/${this.semantic.name}`
+      return Api.Schema.Routing.createReferencePath({
+        type: this.semantic.name,
+      })
     }
 
     if (this.semantic instanceof GraphQLEnumType) {
-      return `/reference/${this.semantic.name}`
+      return Api.Schema.Routing.createReferencePath({
+        type: this.semantic.name,
+      })
     }
 
     if (this.semantic instanceof GraphQLInputObjectType) {
-      return `/reference/${this.semantic.name}`
+      return Api.Schema.Routing.createReferencePath({
+        type: this.semantic.name,
+      })
     }
 
     return null
@@ -488,41 +505,65 @@ class SemanticContext {
 }
 
 /**
- * Parse GraphQL code into interactive tokens with semantic information
+ * Error types for GraphQL parsing
+ */
+export type ParseError =
+  | { readonly _tag: 'InvalidInput'; readonly message: string }
+  | { readonly _tag: 'DocumentTooLarge'; readonly maxSize: number; readonly actualSize: number }
+  | { readonly _tag: 'TreeSitterError'; readonly message: string }
+  | { readonly _tag: 'ParserInitError'; readonly message: string }
+
+const makeParseError = {
+  invalidInput: (message: string): ParseError => ({ _tag: 'InvalidInput', message }),
+  documentTooLarge: (maxSize: number, actualSize: number): ParseError => ({
+    _tag: 'DocumentTooLarge',
+    maxSize,
+    actualSize,
+  }),
+  treeSitterError: (message: string): ParseError => ({ _tag: 'TreeSitterError', message }),
+  parserInitError: (message: string): ParseError => ({ _tag: 'ParserInitError', message }),
+}
+
+/**
+ * Parse GraphQL code into interactive tokens with semantic information (Either version)
  *
  * @param code - The raw GraphQL code to parse
  * @param annotations - CodeHike annotations that might affect rendering
  * @param schema - Optional GraphQL schema for semantic analysis
- * @returns Array of tokens representing the parsed code
+ * @returns Either with array of tokens on right or ParseError on left
  */
-export async function parseGraphQLWithTreeSitter(
+export async function parseGraphQLWithTreeSitterEither(
   code: string,
   annotations: CodeAnnotation[] = [],
   schema?: GraphQLSchema,
-): Promise<GraphQLToken[]> {
+): Promise<Either.Either<GraphQLToken[], ParseError>> {
   // Validate input
   if (!code || typeof code !== 'string') {
-    throw new Error('Invalid GraphQL code: code must be a non-empty string')
+    return Either.left(makeParseError.invalidInput('Invalid GraphQL code: code must be a non-empty string'))
   }
 
   // Prevent parsing extremely large documents that could cause performance issues
-  if (code.length > 100_000) {
-    throw new Error('GraphQL document too large: maximum 100,000 characters allowed')
+  const maxSize = 100_000
+  if (code.length > maxSize) {
+    return Either.left(makeParseError.documentTooLarge(maxSize, code.length))
   }
 
   // Step 1: Parse with tree-sitter
-  const parser = await getParser()
+  let parser: WebTreeSitter.Parser
+  try {
+    parser = await getParser()
+  } catch (error) {
+    return Either.left(makeParseError.parserInitError(
+      error instanceof Error ? error.message : 'Failed to initialize parser',
+    ))
+  }
+
   const tree = parser.parse(code)
 
   if (!tree) {
-    throw new Error('Tree-sitter failed to parse GraphQL code')
+    return Either.left(makeParseError.treeSitterError('Tree-sitter failed to parse GraphQL code'))
   }
 
-  // Check if tree-sitter found syntax errors (disabled for now as it may be too strict)
-  // if (tree.rootNode.hasError) {
-  //   throw new Error('GraphQL syntax error detected by tree-sitter parser')
-  // }
-
   try {
     // Step 2: Walk tree and attach semantics
     const tokens = collectTokensWithSemantics(tree, code, schema, annotations)
@@ -530,26 +571,53 @@ export async function parseGraphQLWithTreeSitter(
     // Step 3: Add error hint tokens after invalid fields
     const tokensWithHints = addErrorHintTokens(tokens, code, annotations)
 
-    return tokensWithHints
+    return Either.right(tokensWithHints)
+  } catch (error) {
+    return Either.left(makeParseError.treeSitterError(
+      error instanceof Error ? error.message : 'Failed to process tokens',
+    ))
   } finally {
-    // ## Tree-sitter Resource Lifecycle Management
-    //
-    // Tree-sitter creates native WASM objects that must be explicitly freed to prevent memory leaks.
-    // The tree object holds references to parsed nodes and internal parser state that won't be
-    // garbage collected automatically by JavaScript.
-    //
-    // Critical cleanup points:
-    // 1. Always call tree.delete() in a finally block to ensure cleanup even on errors
-    // 2. Do not access tree or any of its nodes after calling delete()
-    // 3. The parser instance is cached globally and reused across multiple parsing calls
-    //
-    // Memory safety: Once tree.delete() is called, all WebTreeSitter.Node references become invalid.
-    // Our tokens hold references to these nodes, but only use their text and position properties
-    // which are copied during token creation, so the nodes can be safely deleted.
+    // Tree-sitter Resource Lifecycle Management
     tree.delete()
   }
 }
 
+/**
+ * Parse GraphQL code into interactive tokens with semantic information
+ *
+ * @param code - The raw GraphQL code to parse
+ * @param annotations - CodeHike annotations that might affect rendering
+ * @param schema - Optional GraphQL schema for semantic analysis
+ * @returns Array of tokens representing the parsed code
+ * @deprecated Use parseGraphQLWithTreeSitterEither for better error handling
+ */
+export async function parseGraphQLWithTreeSitter(
+  code: string,
+  annotations: CodeAnnotation[] = [],
+  schema?: GraphQLSchema,
+): Promise<GraphQLToken[]> {
+  const result = await parseGraphQLWithTreeSitterEither(code, annotations, schema)
+
+  if (Either.isLeft(result)) {
+    const error = result.left
+    switch (error._tag) {
+      case 'InvalidInput':
+        throw new Error(error.message)
+      case 'DocumentTooLarge':
+        throw new Error(`GraphQL document too large: maximum ${error.maxSize} characters allowed`)
+      case 'TreeSitterError':
+      case 'ParserInitError':
+        throw new Error(error.message)
+      default: {
+        const exhaustiveCheck: never = error
+        throw new Error(`Unhandled parse error: ${JSON.stringify(exhaustiveCheck)}`)
+      }
+    }
+  }
+
+  return result.right
+}
+
 /**
  * Get or create the tree-sitter parser instance
  */

package/src/template/components/GraphQLInteractive/tests/parser-error-hint.test.ts

@@ -9,7 +9,7 @@ describe('parseGraphQLWithTreeSitter - error hints', () => {
       type Query {
         pokemon(id: ID!): Pokemon
       }
-      
+
       type Pokemon {
         id: ID!
         name: String!
@@ -48,7 +48,7 @@ describe('parseGraphQLWithTreeSitter - error hints', () => {
       type Query {
         pokemon(id: ID!): Pokemon
       }
-      
+
       type Pokemon {
         id: ID!
         name: String!
@@ -78,7 +78,7 @@ describe('parseGraphQLWithTreeSitter - error hints', () => {
       type Query {
         pokemon(id: ID!): Pokemon
       }
-      
+
       type Pokemon {
         id: ID!
         name: String!

package/src/template/components/GraphQLInteractive/tests/parser.test.ts

@@ -1,93 +1,104 @@
 import { buildSchema } from 'graphql'
 import { describe, expect, test } from 'vitest'
+import { Test } from '../../../../../tests/unit/helpers/test.js'
 import { parseGraphQLWithTreeSitter } from '../lib/parser.js'
 import { isArgument } from '../lib/semantic-nodes.js'
 
 describe('parseGraphQLWithTreeSitter', () => {
-  describe('argument parsing', () => {
-    test('should recognize argument names as interactive tokens', async () => {
-      const schema = buildSchema(`
+  interface ArgumentParsingCase {
+    schemaSDL: string
+    code: string
+    checks: Array<{
+      tokenText: string
+      isArgument: boolean
+      expectedInteractive?: boolean
+      expectedUrl?: string
+      checkVariable?: boolean
+    }>
+  }
+
+  // dprint-ignore
+  Test.suite<ArgumentParsingCase>('argument parsing', [
+    {
+      name: 'should recognize argument names as interactive tokens',
+      schemaSDL: `
         type Query {
           pokemon(id: ID!): String
         }
-      `)
-
-      const code = `query {
+      `,
+      code: `query {
         pokemon(id: "123") {
           __typename
         }
-      }`
-
-      const tokens = await parseGraphQLWithTreeSitter(code, [], schema)
-
-      // Find the argument "id" token
-      const argumentToken = tokens.find(t =>
-        t.text === 'id'
-        && isArgument(t.semantic)
-      )
-
-      expect(argumentToken).toBeDefined()
-      expect(argumentToken?.polen.isInteractive()).toBe(true)
-      expect(argumentToken?.polen.getReferenceUrl()).toBe('/reference/Query#pokemon__id')
-    })
-
-    test('should handle multiple arguments', async () => {
-      const schema = buildSchema(`
+      }`,
+      checks: [
+        { tokenText: 'id', isArgument: true, expectedInteractive: true, expectedUrl: '/reference/Query#pokemon__id' },
+      ],
+    },
+    {
+      name: 'should handle multiple arguments',
+      schemaSDL: `
         type Query {
           search(query: String!, limit: Int, offset: Int): [String!]!
         }
-      `)
-
-      const code = `query {
+      `,
+      code: `query {
         search(query: "test", limit: 10) {
           __typename
         }
-      }`
-
-      const tokens = await parseGraphQLWithTreeSitter(code, [], schema)
-
-      const queryArg = tokens.find(t => t.text === 'query' && isArgument(t.semantic))
-      const limitArg = tokens.find(t => t.text === 'limit' && isArgument(t.semantic))
-
-      expect(queryArg).toBeDefined()
-      expect(queryArg?.polen.isInteractive()).toBe(true)
-      expect(queryArg?.polen.getReferenceUrl()).toBe('/reference/Query#search__query')
-
-      expect(limitArg).toBeDefined()
-      expect(limitArg?.polen.isInteractive()).toBe(true)
-      expect(limitArg?.polen.getReferenceUrl()).toBe('/reference/Query#search__limit')
-    })
-
-    test('should handle arguments with variables', async () => {
-      const schema = buildSchema(`
+      }`,
+      checks: [
+        { tokenText: 'query', isArgument: true, expectedInteractive: true, expectedUrl: '/reference/Query#search__query' },
+        { tokenText: 'limit', isArgument: true, expectedInteractive: true, expectedUrl: '/reference/Query#search__limit' },
+      ],
+    },
+    {
+      name: 'should handle arguments with variables',
+      schemaSDL: `
         type Query {
           pokemon(id: ID!): String
         }
-      `)
-
-      const code = `query GetPokemon($pokemonId: ID!) {
+      `,
+      code: `query GetPokemon($pokemonId: ID!) {
         pokemon(id: $pokemonId) {
           __typename
         }
-      }`
-
-      const tokens = await parseGraphQLWithTreeSitter(code, [], schema)
-
-      // The argument name "id" should still be recognized even when value is a variable
-      const idArgument = tokens.find(t =>
-        t.text === 'id'
-        && isArgument(t.semantic)
-      )
-
-      expect(idArgument).toBeDefined()
-      expect(idArgument?.polen.isInteractive()).toBe(true)
-
-      // Variable tokens - basic implementation completed
-      const variable = tokens.find(t => t.text === '$pokemonId')
-      if (variable && variable.semantic && 'kind' in variable.semantic) {
-        expect(variable.semantic.kind).toBe('Variable')
+      }`,
+      checks: [
+        { tokenText: 'id', isArgument: true, expectedInteractive: true },
+        { tokenText: '$pokemonId', isArgument: false, checkVariable: true },
+      ],
+    },
+  ], async ({ schemaSDL, code, checks }) => {
+    const schema = buildSchema(schemaSDL)
+    const tokens = await parseGraphQLWithTreeSitter(code, [], schema)
+    
+    for (const check of checks) {
+      const token = tokens.find(t => {
+        if (check.isArgument) {
+          return t.text === check.tokenText && isArgument(t.semantic)
+        }
+        return t.text === check.tokenText
+      })
+      
+      if (check.isArgument || check.expectedInteractive !== undefined || check.expectedUrl) {
+        expect(token).toBeDefined()
       }
-    })
+      
+      if (token) {
+        if (check.expectedInteractive !== undefined) {
+          expect(token.polen.isInteractive()).toBe(check.expectedInteractive)
+        }
+        
+        if (check.expectedUrl) {
+          expect(token.polen.getReferenceUrl()).toBe(check.expectedUrl)
+        }
+        
+        if (check.checkVariable && token.semantic && 'kind' in token.semantic) {
+          expect(token.semantic.kind).toBe('Variable')
+        }
+      }
+    }
   })
 
   describe('field parsing', () => {

package/src/template/components/HamburgerMenu.tsx

@@ -1,14 +1,29 @@
 import type { Content } from '#api/content/$'
+import type { React } from '#dep/react/index'
 import { Cross2Icon, HamburgerMenuIcon } from '@radix-ui/react-icons'
 import { Box, Flex, IconButton, Text } from '@radix-ui/themes'
 import { useEffect } from 'react'
 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
+
 export interface HamburgerMenuProps {
   isOpen: boolean
   onToggle: () => void
   onClose: () => void
-  sidebarData: Content.Item[]
+  sidebarData: TemplateItem[]
+  basePath?: string
+  topContent?: React.ReactNode
 }
 
 export const HamburgerMenu: React.FC<HamburgerMenuProps> = ({
@@ -16,6 +31,8 @@ export const HamburgerMenu: React.FC<HamburgerMenuProps> = ({
   onToggle,
   onClose,
   sidebarData,
+  basePath,
+  topContent,
 }) => {
   // Prevent body scroll when mobile menu is open
   useEffect(() => {
@@ -87,7 +104,11 @@ export const HamburgerMenu: React.FC<HamburgerMenuProps> = ({
                 <Cross2Icon width='18' height='18' />
               </IconButton>
             </Flex>
-            <Sidebar data={sidebarData} />
+            <Sidebar
+              data={sidebarData}
+              {...(basePath !== undefined && { basePath })}
+              {...(topContent !== undefined && { topContent })}
+            />
           </Box>
         </>
       )}

package/src/template/components/Link.tsx

@@ -2,7 +2,7 @@ import type { FC } from 'react'
 import type { LinkProps as LinkPropsReactRouter } from 'react-router'
 import { Link as LinkReactRouter, useLocation } from 'react-router'
 // todo: #lib/kit-temp does not work as import
-import { ObjPartition } from '../../lib/kit-temp.js'
+import { ObjPartition } from '#lib/kit-temp'
 import { useClientOnly } from '../hooks/useClientOnly.js'
 import type { LinkPropsRadix } from './RadixLink.js'
 import { LinkRadix } from './RadixLink.js'

package/src/template/components/Logo.tsx

@@ -1,18 +1,50 @@
 import { Box, Flex, Text } from '@radix-ui/themes'
+import * as React from 'react'
+import { useTheme } from '../contexts/ThemeContext.js'
+
+interface LogoConfig {
+  light: string
+  dark: string
+  mode: 'single' | 'dual'
+  designedFor: 'light' | 'dark'
+}
 
 interface Props {
-  src: string
+  src: string | LogoConfig
   title?: string
   height?: number
   showTitle?: boolean
 }
 
 export const Logo: React.FC<Props> = ({ src, title, height = 30, showTitle = true }) => {
+  const { appearance } = useTheme()
+
+  // Handle both legacy string src and new LogoConfig
+  let logoSrc: string
+  let needsInvert = false
+
+  if (typeof src === 'string') {
+    // Legacy mode - just use the string as-is
+    logoSrc = src
+  } else {
+    // New mode with logo configuration
+    if (src.mode === 'dual') {
+      // Use theme-specific logo directly
+      logoSrc = appearance === 'dark' ? src.dark : src.light
+    } else {
+      // Single logo - check if invert needed
+      logoSrc = src.light // Same file for both in single mode
+      // Invert when: logo designed for light mode but we're in dark mode, or vice versa
+      needsInvert = (src.designedFor === 'light' && appearance === 'dark')
+        || (src.designedFor === 'dark' && appearance === 'light')
+    }
+  }
+
   return (
     <Flex align='center' gap='2'>
       <Box style={{ height, display: `flex`, alignItems: `center` }}>
         <img
-          src={src}
+          src={logoSrc}
           alt={title}
           height={height}
           className='polen-logo'
@@ -20,6 +52,7 @@ export const Logo: React.FC<Props> = ({ src, title, height = 30, showTitle = tru
             height: `100%`,
             width: `auto`,
             transition: `filter 0.2s ease-in-out`,
+            filter: needsInvert ? 'invert(1)' : undefined,
           }}
         />
       </Box>
@@ -28,19 +61,6 @@ export const Logo: React.FC<Props> = ({ src, title, height = 30, showTitle = tru
           {title}
         </Text>
       )}
-      <style>
-        {`
-          .polen-logo {
-            filter: none;
-          }
-          
-          @media (prefers-color-scheme: dark) {
-            .polen-logo {
-              filter: invert(1);
-            }
-          }
-        `}
-      </style>
     </Flex>
   )
 }

package/src/template/components/MissingSchema.tsx

@@ -1,3 +1,5 @@
-export const MissingSchema = () => {
+import type { React } from '#dep/react/index'
+
+export const MissingSchema: React.FC = () => {
   return <div>No content to show. There is no schema to work with.</div>
 }