polen 0.10.0-next.11 → 0.10.0-next.13

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

@@ -0,0 +1,250 @@
+import type { React } from '#dep/react/index'
+import { React as ReactHooks } from '#dep/react/index'
+import type { GraphQLSchema } from 'graphql'
+import { useNavigate } from 'react-router'
+import { analyze } from '../analysis.ts'
+import { useTooltipState } from '../hooks/use-tooltip-state.ts'
+import { createSimplePositionCalculator } from '../positioning-simple.ts'
+import { createPolenSchemaResolver } from '../schema-integration.ts'
+import type { Identifier } from '../types.ts'
+import { CopyButton } from './CopyButton.tsx'
+import { graphqlDocumentStyles } from './graphql-document-styles.ts'
+import { IdentifierLink } 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 = ReactHooks.useRef<HTMLDivElement>(null)
+  const [isReady, setIsReady] = ReactHooks.useState(false)
+
+  // Use tooltip state management
+  const tooltipState = useTooltipState({
+    showDelay: 300,
+    hideDelay: 200, // Increased for smoother experience
+    allowMultiplePins: true,
+  })
+
+  // Handle escape key to unpin all
+  ReactHooks.useEffect(() => {
+    const handleKeyDown = (event: KeyboardEvent) => {
+      if (event.key === 'Escape') {
+        tooltipState.unpinAll()
+      }
+    }
+
+    document.addEventListener('keydown', handleKeyDown)
+    return () => {
+      document.removeEventListener('keydown', handleKeyDown)
+    }
+  }, [tooltipState])
+
+  // Layer 1: Parse and analyze
+  const analysisResult = ReactHooks.useMemo(() => {
+    if (plain) return null
+    const result = analyze(children, { schema })
+    return result
+  }, [children, plain, schema])
+
+  // Layer 2: Schema resolution
+  const resolver = ReactHooks.useMemo(() => {
+    if (!schema || plain) return null
+    return createPolenSchemaResolver(schema)
+  }, [schema, plain])
+
+  const resolutions = ReactHooks.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 = ReactHooks.useMemo(() => {
+    if (plain) return null
+    return createSimplePositionCalculator()
+  }, [plain])
+
+  const [positions, setPositions] = ReactHooks.useState<Map<string, { position: any; identifier: Identifier }>>(
+    new Map(),
+  )
+
+  // Prepare code block and calculate positions after render
+  ReactHooks.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
+  ReactHooks.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 = ReactHooks.useMemo(() => {
+    if (!validate || !analysisResult || !schema) return []
+    return analysisResult.errors
+  }, [validate, analysisResult, schema])
+
+  return (
+    <>
+      <style dangerouslySetInnerHTML={{ __html: graphqlDocumentStyles }} />
+      <div
+        ref={containerRef}
+        className={`graphql-document ${className} ${debug ? 'graphql-debug-mode' : ''} ${
+          !isReady && !plain ? 'graphql-loading' : ''
+        }`}
+      >
+        {/* Base syntax highlighting */}
+        {highlightedHtml ? <div dangerouslySetInnerHTML={{ __html: highlightedHtml }} /> : (
+          <pre className='shiki'>
+            <code>{children}</code>
+          </pre>
+        )}
+
+        {/* Copy button */}
+        {!plain && (
+          <CopyButton
+            text={children}
+            className='graphql-document-copy'
+            size='2'
+          />
+        )}
+
+        {/* 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={tooltipState.isOpen(id)}
+                  isPinned={tooltipState.isPinned(id)}
+                  onHoverStart={() => tooltipState.onHoverStart(id)}
+                  onHoverEnd={() => tooltipState.onHoverEnd(id)}
+                  onTogglePin={() => tooltipState.onTogglePin(id)}
+                  onTooltipHover={() => tooltipState.onTooltipHover(id)}
+                />
+              )
+            })}
+          </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>
+    </>
+  )
+}

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}
+    />
+  )
+}

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

@@ -0,0 +1,197 @@
+/**
+ * GraphQL Identifier Popover using Radix Themes
+ *
+ * Displays rich information about GraphQL identifiers on hover/click
+ */
+
+import type { React } from '#dep/react/index'
+import { Cross2Icon } from '@radix-ui/react-icons'
+import { Badge, Box, Card, Flex, IconButton, Link, Popover, Text } from '@radix-ui/themes'
+import type { Documentation } from '../schema-integration.ts'
+import type { Identifier } from '../types.ts'
+
+export interface GraphQLIdentifierPopoverProps {
+  /** The identifier being shown */
+  identifier: Identifier
+  /** Documentation from schema */
+  documentation: Documentation
+  /** Whether this identifier has an error */
+  hasError?: boolean
+  /** Reference URL for "View docs" link */
+  referenceUrl: string
+  /** Whether popover is open */
+  open: boolean
+  /** Whether popover is pinned */
+  isPinned: boolean
+  /** Callback when open state changes */
+  onOpenChange: (open: boolean) => void
+  /** Callback to navigate to docs */
+  onNavigate?: (url: string) => void
+  /** The trigger element */
+  children: React.ReactNode
+}
+
+/**
+ * Popover content for GraphQL identifiers
+ */
+export const GraphQLIdentifierPopover: React.FC<GraphQLIdentifierPopoverProps> = ({
+  identifier,
+  documentation,
+  hasError = false,
+  referenceUrl,
+  open,
+  isPinned,
+  onOpenChange,
+  onNavigate,
+  children,
+}) => {
+  // Determine badge color based on identifier kind
+  const getBadgeColor = () => {
+    switch (identifier.kind) {
+      case 'Type':
+        return 'blue'
+      case 'Field':
+        return 'green'
+      case 'Argument':
+        return 'orange'
+      case 'Variable':
+        return 'purple'
+      case 'Directive':
+        return 'amber'
+      case 'Fragment':
+        return 'cyan'
+      default:
+        return 'gray'
+    }
+  }
+
+  return (
+    <Popover.Root open={open} onOpenChange={onOpenChange}>
+      <Popover.Trigger>
+        {children}
+      </Popover.Trigger>
+
+      <Popover.Content
+        className='graphql-identifier-popover'
+        style={{ maxWidth: 400 }}
+        onInteractOutside={(e) => {
+          // Prevent closing when clicking inside popover if pinned
+          if (isPinned) {
+            e.preventDefault()
+          }
+        }}
+      >
+        <Flex direction='column' gap='2'>
+          {/* Header with name, kind, and close button */}
+          <Flex justify='between' align='center'>
+            <Flex align='center' gap='2'>
+              <Text size='2' weight='bold'>
+                {identifier.name}
+              </Text>
+              <Badge color={getBadgeColor()} size='1'>
+                {identifier.kind}
+              </Badge>
+            </Flex>
+            {isPinned && (
+              <IconButton
+                size='1'
+                variant='ghost'
+                onClick={() => onOpenChange(false)}
+                aria-label='Close popover'
+              >
+                <Cross2Icon />
+              </IconButton>
+            )}
+          </Flex>
+
+          {/* Type signature */}
+          <Box>
+            <Text size='1' color='gray'>
+              Type: <Text as='span' size='1' style={{ fontFamily: 'monospace' }}>{documentation.typeInfo}</Text>
+            </Text>
+          </Box>
+
+          {/* Description */}
+          {documentation.description && (
+            <Box>
+              <Text size='1'>
+                {documentation.description}
+              </Text>
+            </Box>
+          )}
+
+          {/* Default value for arguments */}
+          {documentation.defaultValue && (
+            <Box>
+              <Text size='1' color='gray'>
+                Default:{' '}
+                <Text as='span' size='1' style={{ fontFamily: 'monospace' }}>{documentation.defaultValue}</Text>
+              </Text>
+            </Box>
+          )}
+
+          {/* Deprecation warning */}
+          {documentation.deprecated && (
+            <Box
+              style={{
+                padding: '8px',
+                backgroundColor: 'var(--amber-2)',
+                borderRadius: '4px',
+                border: '1px solid var(--amber-6)',
+              }}
+            >
+              <Text size='1' color='amber'>
+                ⚠️ Deprecated: {documentation.deprecated.reason}
+              </Text>
+              {documentation.deprecated.replacement && (
+                <Text size='1' color='amber'>
+                  Use {documentation.deprecated.replacement} instead.
+                </Text>
+              )}
+            </Box>
+          )}
+
+          {/* Error message */}
+          {hasError && (
+            <Box
+              style={{
+                padding: '8px',
+                backgroundColor: 'var(--red-2)',
+                borderRadius: '4px',
+                border: '1px solid var(--red-6)',
+              }}
+            >
+              <Text size='1' color='red'>
+                ❌ {identifier.kind} not found in schema
+              </Text>
+            </Box>
+          )}
+
+          {/* Schema path */}
+          <Box>
+            <Text size='1' color='gray'>
+              Path: {identifier.schemaPath.join(' → ')}
+            </Text>
+          </Box>
+
+          {/* View docs link */}
+          {onNavigate && !hasError && (
+            <Box>
+              <Link
+                size='1'
+                href={referenceUrl}
+                onClick={(e: React.MouseEvent) => {
+                  e.preventDefault()
+                  onNavigate(referenceUrl)
+                  onOpenChange(false)
+                }}
+              >
+                View full documentation →
+              </Link>
+            </Box>
+          )}
+        </Flex>
+      </Popover.Content>
+    </Popover.Root>
+  )
+}