polen 0.10.0-next.11 → 0.10.0-next.12

package/src/lib/graphql-document/components/GraphQLDocument.tsx

@@ -0,0 +1,284 @@
+import type { React } from '#dep/react/index'
+import type { GraphQLSchema } from 'graphql'
+import { useEffect, useMemo, useRef, useState } from 'react'
+import { useNavigate } from 'react-router'
+import { analyze } from '../analysis.ts'
+import { createSimplePositionCalculator } from '../positioning-simple.ts'
+import { createPolenSchemaResolver } from '../schema-integration.ts'
+import type { Identifier } from '../types.ts'
+import { hoverTooltipStyles } from './HoverTooltip.tsx'
+import { IdentifierLink } from './IdentifierLink.tsx'
+import { identifierLinkStyles } from './IdentifierLink.tsx'
+
+/**
+ * Options for the GraphQL document component
+ */
+export interface GraphQLDocumentOptions {
+  /** Whether to show debug overlays */
+  debug?: boolean
+  /** Whether to disable interactive features */
+  plain?: boolean
+  /** Custom navigation handler */
+  onNavigate?: (url: string) => void
+  /** Whether to validate against schema */
+  validate?: boolean
+  /** Custom class name for the container */
+  className?: string
+}
+
+/**
+ * Props for the GraphQL document component
+ */
+export interface GraphQLDocumentProps {
+  /** The GraphQL document source code */
+  children: string
+  /** GraphQL schema for validation and linking */
+  schema?: GraphQLSchema
+  /** Component options */
+  options?: GraphQLDocumentOptions
+  /** Pre-rendered Shiki HTML (from build time) */
+  highlightedHtml?: string
+}
+
+/**
+ * Interactive GraphQL document component
+ *
+ * Transforms static GraphQL code blocks into interactive documentation
+ * with hyperlinks, tooltips, and schema validation.
+ */
+export const GraphQLDocument: React.FC<GraphQLDocumentProps> = ({
+  children,
+  schema,
+  options = {},
+  highlightedHtml,
+}) => {
+  const {
+    debug = false,
+    plain = false,
+    onNavigate,
+    validate = true,
+    className = '',
+  } = options
+
+  const navigate = useNavigate()
+  const handleNavigate = onNavigate || ((url: string) => navigate(url))
+
+  // Container ref for positioning calculations
+  const containerRef = useRef<HTMLDivElement>(null)
+  const [isReady, setIsReady] = useState(false)
+  const [openTooltipId, setOpenTooltipId] = useState<string | null>(null)
+
+  // Handle click outside to close tooltips
+  useEffect(() => {
+    if (!openTooltipId) return
+
+    const handleClickOutside = (event: MouseEvent) => {
+      // Check if click is outside the tooltip and identifier links
+      const target = event.target as HTMLElement
+
+      // Don't close if clicking on an identifier link or tooltip
+      if (
+        target.closest('.graphql-identifier-overlay')
+        || target.closest('.graphql-hover-tooltip')
+      ) {
+        return
+      }
+
+      // Close the tooltip
+      setOpenTooltipId(null)
+    }
+
+    // Add event listener
+    document.addEventListener('mousedown', handleClickOutside)
+
+    return () => {
+      document.removeEventListener('mousedown', handleClickOutside)
+    }
+  }, [openTooltipId])
+
+  // Layer 1: Parse and analyze
+  const analysisResult = useMemo(() => {
+    if (plain) return null
+    const result = analyze(children, { schema })
+    return result
+  }, [children, plain, schema])
+
+  // Layer 2: Schema resolution
+  const resolver = useMemo(() => {
+    if (!schema || plain) return null
+    return createPolenSchemaResolver(schema)
+  }, [schema, plain])
+
+  const resolutions = useMemo(() => {
+    if (!analysisResult || !resolver) {
+      return new Map()
+    }
+
+    const results = new Map()
+    for (const [position, identifier] of analysisResult.identifiers.byPosition) {
+      const resolution = resolver.resolveIdentifier(identifier)
+      if (resolution) {
+        results.set(position, resolution)
+      }
+    }
+    return results
+  }, [analysisResult, resolver])
+
+  // Layer 3: Position calculation
+  const positionCalculator = useMemo(() => {
+    if (plain) return null
+    return createSimplePositionCalculator()
+  }, [plain])
+
+  const [positions, setPositions] = useState<Map<string, { position: any; identifier: Identifier }>>(new Map())
+
+  // Prepare code block and calculate positions after render
+  useEffect(() => {
+    if (!containerRef.current || !analysisResult || !positionCalculator || plain) {
+      return
+    }
+
+    // Get the code element within the container
+    const codeElement = containerRef.current.querySelector('pre.shiki code')
+      || containerRef.current.querySelector('pre code')
+      || containerRef.current.querySelector('code')
+    if (!codeElement) {
+      return
+    }
+
+    // Prepare the code block (wrap identifiers)
+    const identifiers = Array.from(analysisResult.identifiers.byPosition.values())
+    positionCalculator.prepareCodeBlock(codeElement as Element, identifiers)
+
+    // Get positions after DOM update
+    requestAnimationFrame(() => {
+      // Pass containerRef.current as the reference element for positioning
+      if (containerRef.current) {
+        const newPositions = positionCalculator.getIdentifierPositions(codeElement as Element, containerRef.current)
+        setPositions(newPositions)
+        setIsReady(true)
+      }
+    })
+  }, [analysisResult, positionCalculator, plain, highlightedHtml])
+
+  // Handle resize events
+  useEffect(() => {
+    if (!containerRef.current || !positionCalculator || plain) return
+
+    const handleResize = () => {
+      const codeElement = containerRef.current?.querySelector('pre.shiki code')
+        || containerRef.current?.querySelector('pre code')
+        || containerRef.current?.querySelector('code')
+      if (codeElement && containerRef.current) {
+        const newPositions = positionCalculator.getIdentifierPositions(codeElement as Element, containerRef.current)
+        setPositions(newPositions)
+      }
+    }
+
+    window.addEventListener('resize', handleResize)
+    return () => window.removeEventListener('resize', handleResize)
+  }, [positionCalculator, plain])
+
+  // Validation errors
+  const validationErrors = useMemo(() => {
+    if (!validate || !analysisResult || !schema) return []
+    return analysisResult.errors
+  }, [validate, analysisResult, schema])
+
+  return (
+    <>
+      {/* Inject styles */}
+      <style dangerouslySetInnerHTML={{ __html: identifierLinkStyles + '\n' + hoverTooltipStyles }} />
+
+      <div
+        ref={containerRef}
+        className={`graphql-document ${className} ${debug ? 'graphql-debug-mode' : ''}`}
+        style={{ position: 'relative' }}
+      >
+        {/* Base syntax highlighting */}
+        {highlightedHtml ? <div dangerouslySetInnerHTML={{ __html: highlightedHtml }} /> : (
+          <pre className='shiki'>
+            <code>{children}</code>
+          </pre>
+        )}
+
+        {/* Interactive overlay layer */}
+        {!plain && isReady && (
+          <div className='graphql-interaction-layer' style={{ pointerEvents: 'none' }}>
+            {Array.from(positions.entries()).map(([id, { position, identifier }]) => {
+              const startPos = identifier.position.start
+              const resolution = resolutions.get(startPos)
+
+              if (!resolution) return null
+
+              return (
+                <IdentifierLink
+                  key={id}
+                  identifier={identifier}
+                  resolution={resolution}
+                  position={position}
+                  onNavigate={handleNavigate}
+                  debug={debug}
+                  isOpen={openTooltipId === id}
+                  onToggle={(open) => setOpenTooltipId(open ? id : null)}
+                />
+              )
+            })}
+          </div>
+        )}
+
+        {/* Validation errors overlay */}
+        {validationErrors.length > 0 && (
+          <div className='graphql-validation-errors'>
+            {validationErrors.map((error: any, index: number) => (
+              <div key={index} className='graphql-error'>
+                {error.message}
+              </div>
+            ))}
+          </div>
+        )}
+      </div>
+    </>
+  )
+}
+
+/**
+ * Default styles for the GraphQL document component
+ */
+export const graphqlDocumentStyles = `
+.graphql-document {
+  position: relative;
+}
+
+.graphql-interaction-layer {
+  position: absolute;
+  top: 0;
+  left: 0;
+  right: 0;
+  bottom: 0;
+  pointer-events: none;
+}
+
+.graphql-interaction-layer > * {
+  pointer-events: auto;
+}
+
+.graphql-validation-errors {
+  margin-top: 1rem;
+  padding: 0.5rem;
+  background-color: var(--red-2);
+  border: 1px solid var(--red-6);
+  border-radius: 4px;
+}
+
+.graphql-error {
+  color: var(--red-11);
+  font-size: 0.875rem;
+  margin: 0.25rem 0;
+}
+
+.graphql-debug-mode [data-graphql-id] {
+  background-color: rgba(59, 130, 246, 0.1);
+  outline: 1px solid rgba(59, 130, 246, 0.3);
+}
+`

package/src/lib/graphql-document/components/GraphQLDocument.unit.test.ts

@@ -0,0 +1,188 @@
+/**
+ * Unit tests for GraphQL Document component logic
+ *
+ * Tests the core functionality without rendering React components
+ */
+
+import { buildSchema } from 'graphql'
+import { describe, expect, it } from 'vitest'
+import { analyze } from '../analysis.ts'
+import { createSimplePositionCalculator } from '../positioning-simple.ts'
+import { analyzeWithSchema, createPolenSchemaResolver } from '../schema-integration.ts'
+
+describe('GraphQLDocument logic', () => {
+  const testSchema = buildSchema(`
+    type Query {
+      user(id: ID!): User
+      users: [User!]!
+    }
+
+    type User {
+      id: ID!
+      name: String!
+      email: String!
+      posts: [Post!]!
+    }
+
+    type Post {
+      id: ID!
+      title: String!
+      content: String!
+      author: User!
+    }
+  `)
+
+  const testQuery = `
+query GetUser($id: ID!) {
+  user(id: $id) {
+    id
+    name
+    email
+    posts {
+      title
+    }
+  }
+}`
+
+  describe('analysis integration', () => {
+    it('should analyze GraphQL document and extract identifiers', () => {
+      const result = analyze(testQuery)
+
+      expect(result.identifiers.byKind.get('Field')).toBeDefined()
+      expect(result.identifiers.byKind.get('Variable')).toBeDefined()
+      expect(result.identifiers.byKind.get('Type')).toBeDefined()
+
+      // Check specific identifiers
+      const fields = result.identifiers.byKind.get('Field') || []
+      const fieldNames = fields.map(f => f.name)
+      expect(fieldNames).toContain('user')
+      expect(fieldNames).toContain('id')
+      expect(fieldNames).toContain('name')
+      expect(fieldNames).toContain('email')
+      expect(fieldNames).toContain('posts')
+      expect(fieldNames).toContain('title')
+    })
+
+    it('should handle empty document', () => {
+      const result = analyze('')
+      expect(result.identifiers.byPosition.size).toBe(0)
+      // Empty string is technically parseable as an empty document
+      expect(result.ast).toBeDefined()
+    })
+  })
+
+  describe('schema resolution integration', () => {
+    it('should resolve identifiers against schema', () => {
+      // Use analyzeWithSchema for proper schema-aware analysis
+      const { analysis, resolutions } = analyzeWithSchema(testQuery, testSchema)
+
+      // Check that analysis found identifiers
+      expect(analysis.identifiers.all.length).toBeGreaterThan(0)
+
+      // Check that we have resolutions
+      expect(resolutions.size).toBeGreaterThan(0)
+
+      // Check that analysis is valid
+      expect(analysis.isValid).toBe(true)
+
+      // Basic check that resolutions were created
+      const hasValidResolutions = Array.from(resolutions.values()).some(
+        res => res.exists && res.referenceUrl.includes('/reference/'),
+      )
+      expect(hasValidResolutions).toBe(true)
+    })
+
+    it('should detect non-existent fields', () => {
+      const invalidQuery = `query { nonExistentField }`
+      const result = analyze(invalidQuery)
+      const resolver = createPolenSchemaResolver(testSchema)
+
+      const field = Array.from(result.identifiers.byPosition.values())[0]
+      const resolution = resolver.resolveIdentifier(field!)
+
+      expect(resolution).toBeDefined()
+      expect(resolution!.exists).toBe(false)
+    })
+  })
+
+  describe('position calculation', () => {
+    it('should create position calculator', () => {
+      const calculator = createSimplePositionCalculator()
+      expect(calculator).toBeDefined()
+      expect(calculator.prepareCodeBlock).toBeDefined()
+      expect(calculator.getIdentifierPositions).toBeDefined()
+    })
+  })
+
+  describe('options handling', () => {
+    it('should skip analysis when plain option is true', () => {
+      const options = { plain: true }
+      // When plain is true, no analysis should be performed
+      expect(options.plain).toBe(true)
+    })
+
+    it('should enable debug mode', () => {
+      const options = { debug: true }
+      expect(options.debug).toBe(true)
+    })
+
+    it('should handle custom navigation', () => {
+      const onNavigate = (url: string) => {
+        expect(url).toContain('/reference/')
+      }
+      const options = { onNavigate }
+      expect(options.onNavigate).toBeDefined()
+    })
+
+    it('should handle validation option', () => {
+      const options = { validate: true }
+      expect(options.validate).toBe(true)
+    })
+
+    it('should handle custom className', () => {
+      const options = { className: 'custom-graphql-block' }
+      expect(options.className).toBe('custom-graphql-block')
+    })
+  })
+
+  describe('validation', () => {
+    it('should validate valid queries', () => {
+      const { analysis, resolutions } = analyzeWithSchema(testQuery, testSchema)
+
+      // Check that validation passed
+      expect(analysis.isValid).toBe(true)
+
+      // Check that we have resolutions
+      expect(resolutions.size).toBeGreaterThan(0)
+
+      // Check that the user field resolved correctly
+      const userResolution = Array.from(resolutions.values()).find(
+        res => res.referenceUrl.includes('query') && res.referenceUrl.includes('user'),
+      )
+
+      if (userResolution) {
+        expect(userResolution.exists).toBe(true)
+      }
+    })
+
+    it('should detect validation errors', () => {
+      const invalidQuery = `
+        query {
+          user {
+            nonExistentField
+          }
+        }
+      `
+
+      const result = analyze(invalidQuery)
+      const resolver = createPolenSchemaResolver(testSchema)
+
+      const resolutions = Array.from(result.identifiers.byPosition.values())
+        .map(id => ({ id, resolution: resolver.resolveIdentifier(id) }))
+
+      const invalidField = resolutions.find(r => r.id.name === 'nonExistentField')
+      expect(invalidField).toBeDefined()
+      expect(invalidField!.resolution!.exists).toBe(false)
+    })
+  })
+})

package/src/lib/graphql-document/components/GraphQLDocumentWithSchema.tsx

@@ -0,0 +1,70 @@
+import type { React } from '#dep/react/index'
+import { useEffect, useState } from 'react'
+import { useGraphQLSchema } from '../schema-context.tsx'
+import { GraphQLDocument, type GraphQLDocumentProps } from './GraphQLDocument.tsx'
+
+// Cache for highlighter
+let highlighterCache: any = null
+
+/**
+ * GraphQL Document component that uses the schema context and handles syntax highlighting
+ */
+export const GraphQLDocumentWithSchema: React.FC<Omit<GraphQLDocumentProps, 'schema' | 'highlightedHtml'>> = (
+  props,
+) => {
+  const schema = useGraphQLSchema()
+  const [mounted, setMounted] = useState(false)
+  const [highlightedHtml, setHighlightedHtml] = useState<string | null>(null)
+
+  useEffect(() => {
+    setMounted(true)
+
+    const loadHighlighter = async () => {
+      try {
+        // Load highlighter if not cached
+        if (!highlighterCache) {
+          const { highlightCode } = await import('#lib/shiki/index')
+          highlighterCache = highlightCode
+        }
+
+        // Generate highlighted HTML
+        const highlighted = await highlighterCache({
+          code: props['children'],
+          lang: 'graphql',
+          theme: 'light',
+        })
+
+        setHighlightedHtml(highlighted)
+      } catch (error) {
+        console.error('Failed to load GraphQL document highlighter:', error)
+      }
+    }
+
+    loadHighlighter()
+  }, [props['children']])
+
+  // Always render the same structure to avoid hydration issues
+  const isInteractive = mounted && schema && highlightedHtml
+
+  if (!isInteractive) {
+    // Static fallback that looks like Shiki output
+    return (
+      <div className='graphql-document graphql-document-static' data-testid='graphql-document'>
+        <pre
+          className='shiki shiki-themes github-light tokyo-night'
+          style={{ backgroundColor: 'var(--shiki-light-bg)', color: 'var(--shiki-light)' }}
+        >
+          <code className="language-graphql">{props['children']}</code>
+        </pre>
+      </div>
+    )
+  }
+
+  return (
+    <GraphQLDocument
+      {...props}
+      schema={schema}
+      highlightedHtml={highlightedHtml}
+    />
+  )
+}