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

package/src/lib/graphql-document/example.ts

@@ -0,0 +1,163 @@
+/**
+ * Example usage of the GraphQL Document Analysis library
+ *
+ * This demonstrates how to use the foundational layer for extracting
+ * identifiers and context from GraphQL documents - the building block
+ * for the interactive GraphQL Document Component.
+ */
+
+import { GraphQLDocument } from './$.ts'
+
+// Example GraphQL query with various constructs
+const exampleQuery = `
+  query GetPokemonWithAbilities($id: ID!, $limit: Int = 10) {
+    pokemon(id: $id) {
+      name
+      abilities(first: $limit) {
+        name
+        isHidden
+        pokemon {
+          name
+        }
+      }
+      ... on ElectricPokemon {
+        voltage
+      }
+    }
+  }
+
+  fragment PokemonBasics on Pokemon {
+    name
+    type
+    level
+  }
+`
+
+/**
+ * Demonstrate basic analysis
+ */
+export const analyzeExample = () => {
+  console.log('🔍 Analyzing GraphQL Document...\n')
+
+  const result = GraphQLDocument.analyze(exampleQuery)
+
+  console.log(`✅ Valid: ${result.isValid}`)
+  console.log(`📊 Total identifiers: ${result.identifiers.all.length}`)
+  console.log(`🚨 Errors: ${result.errors.length}\n`)
+
+  // Show identifiers by kind
+  for (const [kind, identifiers] of result.identifiers.byKind) {
+    console.log(`${getKindEmoji(kind)} ${kind} (${identifiers.length}):`)
+    for (const identifier of identifiers) {
+      const pos = `${identifier.position.line}:${identifier.position.column}`
+      const path = identifier.schemaPath.join(' → ')
+      const parent = identifier.parentType ? ` (in ${identifier.parentType})` : ''
+      console.log(`  • ${identifier.name}${parent} → ${path} @ ${pos}`)
+    }
+    console.log()
+  }
+
+  return result
+}
+
+/**
+ * Demonstrate identifier lookup by position
+ */
+export const demonstratePositionLookup = () => {
+  console.log('📍 Position-based Identifier Lookup...\n')
+
+  const identifiers = GraphQLDocument.extractIdentifiers(exampleQuery)
+
+  // Find identifier at a specific position (e.g., cursor position in an editor)
+  const targetPosition = 180 // Approximate position of "abilities" field
+
+  // Find the closest identifier to this position
+  let closestIdentifier = null
+  let closestDistance = Infinity
+
+  for (const identifier of identifiers.all) {
+    const distance = Math.abs(identifier.position.start - targetPosition)
+    if (distance < closestDistance) {
+      closestDistance = distance
+      closestIdentifier = identifier
+    }
+  }
+
+  if (closestIdentifier) {
+    console.log(`🎯 Identifier near position ${targetPosition}:`)
+    console.log(`   Name: ${closestIdentifier.name}`)
+    console.log(`   Kind: ${closestIdentifier.kind}`)
+    console.log(`   Schema Path: ${closestIdentifier.schemaPath.join(' → ')}`)
+    console.log(`   Context: ${JSON.stringify(closestIdentifier.context, null, 2)}`)
+  }
+}
+
+/**
+ * Demonstrate how this enables hyperlink generation
+ */
+export const demonstrateHyperlinkGeneration = () => {
+  console.log('🔗 Hyperlink Generation Preview...\n')
+
+  const identifiers = GraphQLDocument.extractIdentifiers(exampleQuery)
+
+  // Show how each identifier could become a hyperlink
+  const typeIdentifiers = identifiers.byKind.get('Type') || []
+  const fieldIdentifiers = identifiers.byKind.get('Field') || []
+
+  console.log('📝 Type References → Schema Links:')
+  for (const identifier of typeIdentifiers) {
+    const referenceUrl = `/reference/${identifier.name}`
+    console.log(`  ${identifier.name} → ${referenceUrl}`)
+  }
+
+  console.log('\n📝 Field References → Schema Links:')
+  for (const identifier of fieldIdentifiers.slice(0, 5)) { // Show first 5
+    const referenceUrl = identifier.parentType
+      ? `/reference/${identifier.parentType}#${identifier.name}`
+      : `/reference/${identifier.name}`
+    console.log(`  ${identifier.name} → ${referenceUrl}`)
+  }
+}
+
+/**
+ * Show the foundation for hover tooltips
+ */
+export const demonstrateTooltipFoundation = () => {
+  console.log('💬 Tooltip Foundation...\n')
+
+  const identifiers = GraphQLDocument.extractIdentifiers(exampleQuery)
+
+  // Show context information that would be displayed in tooltips
+  const fieldIdentifiers = identifiers.byKind.get('Field') || []
+
+  for (const identifier of fieldIdentifiers.slice(0, 3)) { // Show first 3
+    console.log(`🏷️  ${identifier.name}:`)
+    console.log(`    Position: Line ${identifier.position.line}, Column ${identifier.position.column}`)
+    console.log(`    Schema Path: ${identifier.schemaPath.join(' → ')}`)
+    console.log(`    Parent Type: ${identifier.parentType || 'Root'}`)
+    console.log(`    Operation: ${identifier.context.operationType || 'None'}`)
+    console.log(`    Selection Path: ${identifier.context.selectionPath.join(' → ')}`)
+    console.log()
+  }
+}
+
+// Helper function
+function getKindEmoji(kind: string): string {
+  const emojis: Record<string, string> = {
+    'Type': '🏷️',
+    'Field': '📋',
+    'Argument': '⚙️',
+    'Variable': '💰',
+    'Directive': '🎯',
+    'Fragment': '🧩',
+  }
+  return emojis[kind] || '❓'
+}
+
+// Run example if executed directly
+if (import.meta.url === `file://${process.argv[1]}`) {
+  analyzeExample()
+  demonstratePositionLookup()
+  demonstrateHyperlinkGeneration()
+  demonstrateTooltipFoundation()
+}

package/src/lib/graphql-document/graphql-document.ts

@@ -0,0 +1,37 @@
+/**
+ * GraphQL Document Component Library
+ *
+ * Transform static GraphQL code blocks into interactive documentation with
+ * hyperlinks, tooltips, and schema validation.
+ *
+ * ## Features
+ * - Hyperlinked identifiers that navigate to reference documentation
+ * - Hover tooltips showing type information and descriptions
+ * - Schema validation with error highlighting
+ * - Build-time GraphQL validation
+ * - Support for all GraphQL operations (queries, mutations, subscriptions, fragments)
+ *
+ * ## Usage
+ * ```typescript
+ * import { GraphQLDocument } from 'polen/lib/graphql-document'
+ *
+ * <GraphQLDocument schema={schema}>
+ *   {`query { user { name } }`}
+ * </GraphQLDocument>
+ * ```
+ *
+ * @see {@link GraphQLDocumentWithSchema} for MDX integration
+ * @see {@link GraphQLDocument} for the main React component
+ */
+
+export * from './analysis.ts'
+export * from './components/index.ts'
+export * from './positioning-simple.ts'
+export * from './schema-integration.ts'
+export * from './types.ts'
+
+// Re-export key functions for convenience
+export { analyze, analyzer, extractIdentifiers } from './analysis.ts'
+export { GraphQLDocument } from './components/GraphQLDocument.tsx'
+export { createSimpleOverlay, createSimplePositionCalculator } from './positioning-simple.ts'
+export { analyzeWithSchema, createPolenSchemaResolver } from './schema-integration.ts'

package/src/lib/graphql-document/positioning-simple.test.ts

@@ -0,0 +1,252 @@
+/**
+ * @vitest-environment jsdom
+ */
+
+import { beforeEach, describe, expect, it } from 'vitest'
+import { createSimpleOverlay, createSimplePositionCalculator } from './positioning-simple.ts'
+import type { Identifier } from './types.ts'
+
+// Helper to create test identifier
+const createTestIdentifier = (
+  name: string,
+  line: number,
+  column: number,
+  kind: Identifier['kind'] = 'Field',
+): Identifier => ({
+  name,
+  kind,
+  position: {
+    start: column - 1,
+    end: column - 1 + name.length,
+    line,
+    column,
+  },
+  schemaPath: [name],
+  context: { selectionPath: [] },
+})
+
+describe('Simple Positioning Engine', () => {
+  describe('SimplePositionCalculator', () => {
+    const calculator = createSimplePositionCalculator()
+
+    it('should wrap identifiers in spans', () => {
+      const container = document.createElement('div')
+      container.innerHTML = `
+        <pre class="shiki">
+          <code>
+            <span class="line">query GetUser {</span>
+            <span class="line">  user {</span>
+            <span class="line">    name</span>
+            <span class="line">  }</span>
+            <span class="line">}</span>
+          </code>
+        </pre>
+      `
+
+      const identifiers = [
+        createTestIdentifier('query', 1, 1),
+        createTestIdentifier('user', 2, 3, 'Field'),
+        createTestIdentifier('name', 3, 5, 'Field'),
+      ]
+
+      calculator.prepareCodeBlock(container, identifiers)
+
+      // Check that identifiers were wrapped
+      const wrappedElements = container.querySelectorAll('[data-graphql-id]')
+      expect(wrappedElements.length).toBe(3)
+
+      // Check first wrapped element
+      const firstWrapped = wrappedElements[0] as HTMLElement
+      expect(firstWrapped.textContent).toBe('query')
+      expect(firstWrapped.getAttribute('data-graphql-name')).toBe('query')
+      expect(firstWrapped.getAttribute('data-graphql-kind')).toBe('Field')
+    })
+
+    it('should handle multiple identifiers in same line', () => {
+      const container = document.createElement('div')
+      container.innerHTML = `
+        <pre class="shiki">
+          <code>
+            <span class="line">query GetUserById($id: ID!) {</span>
+          </code>
+        </pre>
+      `
+
+      const identifiers = [
+        createTestIdentifier('query', 1, 1),
+        createTestIdentifier('GetUserById', 1, 7),
+        createTestIdentifier('$id', 1, 19, 'Variable'),
+        createTestIdentifier('ID', 1, 24, 'Type'),
+      ]
+
+      calculator.prepareCodeBlock(container, identifiers)
+
+      const wrappedElements = container.querySelectorAll('[data-graphql-id]')
+      expect(wrappedElements.length).toBe(4)
+    })
+
+    it('should get positions of wrapped identifiers', () => {
+      const container = document.createElement('div')
+      container.innerHTML = `
+        <pre class="shiki">
+          <code>
+            <span class="line"><span data-graphql-id="0-user-Field" data-graphql-name="user" data-graphql-kind="Field" data-graphql-start="0" data-graphql-end="4" data-graphql-line="1" data-graphql-column="1" data-graphql-path="user">user</span> {</span>
+          </code>
+        </pre>
+      `
+
+      // Mock getBoundingClientRect
+      container.getBoundingClientRect = () => ({
+        top: 0,
+        left: 0,
+        right: 100,
+        bottom: 100,
+        width: 100,
+        height: 100,
+        x: 0,
+        y: 0,
+        toJSON: () => ({}),
+      })
+
+      const userSpan = container.querySelector('[data-graphql-id]') as HTMLElement
+      userSpan.getBoundingClientRect = () => ({
+        top: 10,
+        left: 20,
+        right: 60,
+        bottom: 30,
+        width: 40,
+        height: 20,
+        x: 20,
+        y: 10,
+        toJSON: () => ({}),
+      })
+
+      const positions = calculator.getIdentifierPositions(container)
+
+      expect(positions.size).toBe(1)
+      const result = positions.get('0-user-Field')
+      expect(result).toBeDefined()
+      expect(result!.position).toEqual({
+        top: 10,
+        left: 20,
+        width: 40,
+        height: 20,
+      })
+      expect(result!.identifier.name).toBe('user')
+      expect(result!.identifier.kind).toBe('Field')
+    })
+
+    it('should skip already wrapped identifiers', () => {
+      const container = document.createElement('div')
+      container.innerHTML = `
+        <pre class="shiki">
+          <code>
+            <span class="line"><span data-graphql-id="existing">user</span> {</span>
+          </code>
+        </pre>
+      `
+
+      const identifiers = [
+        createTestIdentifier('user', 1, 1),
+      ]
+
+      calculator.prepareCodeBlock(container, identifiers)
+
+      // Should still only have one wrapped element
+      const wrappedElements = container.querySelectorAll('[data-graphql-id]')
+      expect(wrappedElements.length).toBe(1)
+      expect(wrappedElements[0]!.getAttribute('data-graphql-id')).toBe('existing')
+    })
+
+    it('should handle empty lines gracefully', () => {
+      const container = document.createElement('div')
+      container.innerHTML = `
+        <pre class="shiki">
+          <code>
+            <span class="line">query {</span>
+            <span class="line"></span>
+            <span class="line">  user</span>
+          </code>
+        </pre>
+      `
+
+      const identifiers = [
+        createTestIdentifier('query', 1, 1),
+        createTestIdentifier('user', 3, 3),
+      ]
+
+      expect(() => {
+        calculator.prepareCodeBlock(container, identifiers)
+      }).not.toThrow()
+
+      const wrappedElements = container.querySelectorAll('[data-graphql-id]')
+      expect(wrappedElements.length).toBe(2)
+    })
+  })
+
+  describe('createSimpleOverlay', () => {
+    it('should create positioned overlay element', () => {
+      const position = { top: 10, left: 20, width: 40, height: 20 }
+      const identifier = createTestIdentifier('user', 1, 1)
+
+      const overlay = createSimpleOverlay(position, identifier)
+
+      expect(overlay.style.position).toBe('absolute')
+      expect(overlay.style.top).toBe('10px')
+      expect(overlay.style.left).toBe('20px')
+      expect(overlay.style.width).toBe('40px')
+      expect(overlay.style.height).toBe('20px')
+      expect(overlay.style.cursor).toBe('pointer')
+      expect(overlay.getAttribute('data-graphql-overlay')).toBe('true')
+      expect(overlay.getAttribute('data-graphql-name')).toBe('user')
+      expect(overlay.getAttribute('data-graphql-kind')).toBe('Field')
+    })
+
+    it('should handle click events', () => {
+      const position = { top: 10, left: 20, width: 40, height: 20 }
+      const identifier = createTestIdentifier('user', 1, 1)
+      let clickedIdentifier: Identifier | null = null
+
+      const overlay = createSimpleOverlay(position, identifier, {
+        onClick: (id) => {
+          clickedIdentifier = id
+        },
+      })
+
+      // Simulate click
+      const event = new MouseEvent('click')
+      overlay.dispatchEvent(event)
+
+      expect(clickedIdentifier).toBe(identifier)
+    })
+
+    it('should handle hover events', () => {
+      const position = { top: 10, left: 20, width: 40, height: 20 }
+      const identifier = createTestIdentifier('user', 1, 1)
+      let hoveredIdentifier: Identifier | null = null
+
+      const overlay = createSimpleOverlay(position, identifier, {
+        onHover: (id) => {
+          hoveredIdentifier = id
+        },
+      })
+
+      // Simulate hover
+      const event = new MouseEvent('mouseenter')
+      overlay.dispatchEvent(event)
+
+      expect(hoveredIdentifier).toBe(identifier)
+    })
+
+    it('should apply custom className', () => {
+      const position = { top: 10, left: 20, width: 40, height: 20 }
+      const identifier = createTestIdentifier('user', 1, 1)
+
+      const overlay = createSimpleOverlay(position, identifier, {
+        className: 'custom-overlay-class',
+      })
+
+      expect(overlay.className).toBe('custom-overlay-class')
+    })
+  })
+})