polen 0.10.0-next.9 → 0.10.0

package/src/lib/graphql-change/change-types.ts

@@ -0,0 +1,203 @@
+// dprint-ignore-file
+import type { GraphqlInspector } from '#dep/graphql-inspector/index'
+
+/**
+ * Additional properties that Polen adds to GraphQL Inspector changes
+ */
+export interface ChangeExtensions {
+  message: string
+  path?: string
+  criticality: GraphqlInspector.Core.Criticality
+}
+
+// Type changes
+export interface TypeAddedChange extends GraphqlInspector.Core.TypeAddedChange, ChangeExtensions {}
+export interface TypeRemovedChange extends GraphqlInspector.Core.TypeRemovedChange, ChangeExtensions {}
+export interface TypeKindChangedChange extends GraphqlInspector.Core.TypeKindChangedChange, ChangeExtensions {}
+export interface TypeDescriptionChangedChange extends GraphqlInspector.Core.TypeDescriptionChangedChange, ChangeExtensions {}
+export interface TypeDescriptionAddedChange extends GraphqlInspector.Core.TypeDescriptionAddedChange, ChangeExtensions {}
+export interface TypeDescriptionRemovedChange extends GraphqlInspector.Core.TypeDescriptionRemovedChange, ChangeExtensions {}
+
+// Field changes
+export interface FieldAddedChange extends GraphqlInspector.Core.FieldAddedChange, ChangeExtensions {}
+export interface FieldRemovedChange extends GraphqlInspector.Core.FieldRemovedChange, ChangeExtensions {}
+export interface FieldTypeChangedChange extends GraphqlInspector.Core.FieldTypeChangedChange, ChangeExtensions {}
+// Note: GraphQL Inspector doesn't have FieldDeprecatedChange, it's handled by FieldDeprecationAddedChange
+export interface FieldDeprecationAddedChange extends GraphqlInspector.Core.FieldDeprecationAddedChange, ChangeExtensions {}
+export interface FieldDeprecationRemovedChange extends GraphqlInspector.Core.FieldDeprecationRemovedChange, ChangeExtensions {}
+export interface FieldDeprecationReasonChangedChange extends GraphqlInspector.Core.FieldDeprecationReasonChangedChange, ChangeExtensions {}
+export interface FieldDeprecationReasonAddedChange extends GraphqlInspector.Core.FieldDeprecationReasonAddedChange, ChangeExtensions {}
+export interface FieldDeprecationReasonRemovedChange extends GraphqlInspector.Core.FieldDeprecationReasonRemovedChange, ChangeExtensions {}
+export interface FieldDescriptionChangedChange extends GraphqlInspector.Core.FieldDescriptionChangedChange, ChangeExtensions {}
+export interface FieldDescriptionAddedChange extends GraphqlInspector.Core.FieldDescriptionAddedChange, ChangeExtensions {}
+export interface FieldDescriptionRemovedChange extends GraphqlInspector.Core.FieldDescriptionRemovedChange, ChangeExtensions {}
+
+// Field argument changes
+export interface FieldArgumentAddedChange extends GraphqlInspector.Core.FieldArgumentAddedChange, ChangeExtensions {}
+export interface FieldArgumentRemovedChange extends GraphqlInspector.Core.FieldArgumentRemovedChange, ChangeExtensions {}
+export interface FieldArgumentTypeChangedChange extends GraphqlInspector.Core.FieldArgumentTypeChangedChange, ChangeExtensions {}
+export interface FieldArgumentDescriptionChangedChange extends GraphqlInspector.Core.FieldArgumentDescriptionChangedChange, ChangeExtensions {}
+export interface FieldArgumentDefaultChangedChange extends GraphqlInspector.Core.FieldArgumentDefaultChangedChange, ChangeExtensions {}
+
+// Enum changes
+export interface EnumValueAddedChange extends GraphqlInspector.Core.EnumValueAddedChange, ChangeExtensions {}
+export interface EnumValueRemovedChange extends GraphqlInspector.Core.EnumValueRemovedChange, ChangeExtensions {}
+export interface EnumValueDescriptionChangedChange extends GraphqlInspector.Core.EnumValueDescriptionChangedChange, ChangeExtensions {}
+export interface EnumValueDeprecationReasonAddedChange extends GraphqlInspector.Core.EnumValueDeprecationReasonAddedChange, ChangeExtensions {}
+export interface EnumValueDeprecationReasonChangedChange extends GraphqlInspector.Core.EnumValueDeprecationReasonChangedChange, ChangeExtensions {}
+export interface EnumValueDeprecationReasonRemovedChange extends GraphqlInspector.Core.EnumValueDeprecationReasonRemovedChange, ChangeExtensions {}
+
+// Input field changes
+export interface InputFieldAddedChange extends GraphqlInspector.Core.InputFieldAddedChange, ChangeExtensions {}
+export interface InputFieldRemovedChange extends GraphqlInspector.Core.InputFieldRemovedChange, ChangeExtensions {}
+export interface InputFieldTypeChangedChange extends GraphqlInspector.Core.InputFieldTypeChangedChange, ChangeExtensions {}
+export interface InputFieldDescriptionAddedChange extends GraphqlInspector.Core.InputFieldDescriptionAddedChange, ChangeExtensions {}
+export interface InputFieldDescriptionRemovedChange extends GraphqlInspector.Core.InputFieldDescriptionRemovedChange, ChangeExtensions {}
+export interface InputFieldDescriptionChangedChange extends GraphqlInspector.Core.InputFieldDescriptionChangedChange, ChangeExtensions {}
+export interface InputFieldDefaultValueChangedChange extends GraphqlInspector.Core.InputFieldDefaultValueChangedChange, ChangeExtensions {}
+
+// Union changes
+export interface UnionMemberAddedChange extends GraphqlInspector.Core.UnionMemberAddedChange, ChangeExtensions {}
+export interface UnionMemberRemovedChange extends GraphqlInspector.Core.UnionMemberRemovedChange, ChangeExtensions {}
+
+// Interface changes
+export interface ObjectTypeInterfaceAddedChange extends GraphqlInspector.Core.ObjectTypeInterfaceAddedChange, ChangeExtensions {}
+export interface ObjectTypeInterfaceRemovedChange extends GraphqlInspector.Core.ObjectTypeInterfaceRemovedChange, ChangeExtensions {}
+
+// Directive changes
+export interface DirectiveAddedChange extends GraphqlInspector.Core.DirectiveAddedChange, ChangeExtensions {}
+export interface DirectiveRemovedChange extends GraphqlInspector.Core.DirectiveRemovedChange, ChangeExtensions {}
+export interface DirectiveDescriptionChangedChange extends GraphqlInspector.Core.DirectiveDescriptionChangedChange, ChangeExtensions {}
+export interface DirectiveLocationAddedChange extends GraphqlInspector.Core.DirectiveLocationAddedChange, ChangeExtensions {}
+export interface DirectiveLocationRemovedChange extends GraphqlInspector.Core.DirectiveLocationRemovedChange, ChangeExtensions {}
+export interface DirectiveArgumentAddedChange extends GraphqlInspector.Core.DirectiveArgumentAddedChange, ChangeExtensions {}
+export interface DirectiveArgumentRemovedChange extends GraphqlInspector.Core.DirectiveArgumentRemovedChange, ChangeExtensions {}
+export interface DirectiveArgumentDescriptionChangedChange extends GraphqlInspector.Core.DirectiveArgumentDescriptionChangedChange, ChangeExtensions {}
+export interface DirectiveArgumentDefaultValueChangedChange extends GraphqlInspector.Core.DirectiveArgumentDefaultValueChangedChange, ChangeExtensions {}
+export interface DirectiveArgumentTypeChangedChange extends GraphqlInspector.Core.DirectiveArgumentTypeChangedChange, ChangeExtensions {}
+
+// Schema changes
+export interface SchemaQueryTypeChangedChange extends GraphqlInspector.Core.SchemaQueryTypeChangedChange, ChangeExtensions {}
+export interface SchemaMutationTypeChangedChange extends GraphqlInspector.Core.SchemaMutationTypeChangedChange, ChangeExtensions {}
+export interface SchemaSubscriptionTypeChangedChange extends GraphqlInspector.Core.SchemaSubscriptionTypeChangedChange, ChangeExtensions {}
+
+// Directive usage changes
+export interface DirectiveUsageUnionMemberAddedChange extends GraphqlInspector.Core.DirectiveUsageUnionMemberAddedChange, ChangeExtensions {}
+export interface DirectiveUsageUnionMemberRemovedChange extends GraphqlInspector.Core.DirectiveUsageUnionMemberRemovedChange, ChangeExtensions {}
+export interface DirectiveUsageEnumAddedChange extends GraphqlInspector.Core.DirectiveUsageEnumAddedChange, ChangeExtensions {}
+export interface DirectiveUsageEnumRemovedChange extends GraphqlInspector.Core.DirectiveUsageEnumRemovedChange, ChangeExtensions {}
+export interface DirectiveUsageEnumValueAddedChange extends GraphqlInspector.Core.DirectiveUsageEnumValueAddedChange, ChangeExtensions {}
+export interface DirectiveUsageEnumValueRemovedChange extends GraphqlInspector.Core.DirectiveUsageEnumValueRemovedChange, ChangeExtensions {}
+export interface DirectiveUsageInputObjectAddedChange extends GraphqlInspector.Core.DirectiveUsageInputObjectAddedChange, ChangeExtensions {}
+export interface DirectiveUsageInputObjectRemovedChange extends GraphqlInspector.Core.DirectiveUsageInputObjectRemovedChange, ChangeExtensions {}
+export interface DirectiveUsageFieldAddedChange extends GraphqlInspector.Core.DirectiveUsageFieldAddedChange, ChangeExtensions {}
+export interface DirectiveUsageFieldRemovedChange extends GraphqlInspector.Core.DirectiveUsageFieldRemovedChange, ChangeExtensions {}
+export interface DirectiveUsageScalarAddedChange extends GraphqlInspector.Core.DirectiveUsageScalarAddedChange, ChangeExtensions {}
+export interface DirectiveUsageScalarRemovedChange extends GraphqlInspector.Core.DirectiveUsageScalarRemovedChange, ChangeExtensions {}
+export interface DirectiveUsageObjectAddedChange extends GraphqlInspector.Core.DirectiveUsageObjectAddedChange, ChangeExtensions {}
+export interface DirectiveUsageObjectRemovedChange extends GraphqlInspector.Core.DirectiveUsageObjectRemovedChange, ChangeExtensions {}
+export interface DirectiveUsageInterfaceAddedChange extends GraphqlInspector.Core.DirectiveUsageInterfaceAddedChange, ChangeExtensions {}
+export interface DirectiveUsageInterfaceRemovedChange extends GraphqlInspector.Core.DirectiveUsageInterfaceRemovedChange, ChangeExtensions {}
+export interface DirectiveUsageArgumentDefinitionAddedChange extends GraphqlInspector.Core.DirectiveUsageArgumentDefinitionAddedChange, ChangeExtensions {}
+export interface DirectiveUsageArgumentDefinitionRemovedChange extends GraphqlInspector.Core.DirectiveUsageArgumentDefinitionRemovedChange, ChangeExtensions {}
+export interface DirectiveUsageSchemaAddedChange extends GraphqlInspector.Core.DirectiveUsageSchemaAddedChange, ChangeExtensions {}
+export interface DirectiveUsageSchemaRemovedChange extends GraphqlInspector.Core.DirectiveUsageSchemaRemovedChange, ChangeExtensions {}
+export interface DirectiveUsageFieldDefinitionAddedChange extends GraphqlInspector.Core.DirectiveUsageFieldDefinitionAddedChange, ChangeExtensions {}
+export interface DirectiveUsageFieldDefinitionRemovedChange extends GraphqlInspector.Core.DirectiveUsageFieldDefinitionRemovedChange, ChangeExtensions {}
+export interface DirectiveUsageInputFieldDefinitionAddedChange extends GraphqlInspector.Core.DirectiveUsageInputFieldDefinitionAddedChange, ChangeExtensions {}
+export interface DirectiveUsageInputFieldDefinitionRemovedChange extends GraphqlInspector.Core.DirectiveUsageInputFieldDefinitionRemovedChange, ChangeExtensions {}
+
+/**
+ * Discriminated union of all possible change types
+ */
+export type Change =
+  | TypeAddedChange
+  | TypeRemovedChange
+  | TypeKindChangedChange
+  | TypeDescriptionChangedChange
+  | TypeDescriptionAddedChange
+  | TypeDescriptionRemovedChange
+  | FieldAddedChange
+  | FieldRemovedChange
+  | FieldTypeChangedChange
+  // | FieldDeprecatedChange
+  | FieldDeprecationAddedChange
+  | FieldDeprecationRemovedChange
+  | FieldDeprecationReasonChangedChange
+  | FieldDeprecationReasonAddedChange
+  | FieldDeprecationReasonRemovedChange
+  | FieldDescriptionChangedChange
+  | FieldDescriptionAddedChange
+  | FieldDescriptionRemovedChange
+  | FieldArgumentAddedChange
+  | FieldArgumentRemovedChange
+  | FieldArgumentTypeChangedChange
+  | FieldArgumentDescriptionChangedChange
+  | FieldArgumentDefaultChangedChange
+  | EnumValueAddedChange
+  | EnumValueRemovedChange
+  | EnumValueDescriptionChangedChange
+  | EnumValueDeprecationReasonAddedChange
+  | EnumValueDeprecationReasonChangedChange
+  | EnumValueDeprecationReasonRemovedChange
+  | InputFieldAddedChange
+  | InputFieldRemovedChange
+  | InputFieldTypeChangedChange
+  | InputFieldDescriptionAddedChange
+  | InputFieldDescriptionRemovedChange
+  | InputFieldDescriptionChangedChange
+  | InputFieldDefaultValueChangedChange
+  | UnionMemberAddedChange
+  | UnionMemberRemovedChange
+  | ObjectTypeInterfaceAddedChange
+  | ObjectTypeInterfaceRemovedChange
+  | DirectiveAddedChange
+  | DirectiveRemovedChange
+  | DirectiveDescriptionChangedChange
+  | DirectiveLocationAddedChange
+  | DirectiveLocationRemovedChange
+  | DirectiveArgumentAddedChange
+  | DirectiveArgumentRemovedChange
+  | DirectiveArgumentDescriptionChangedChange
+  | DirectiveArgumentDefaultValueChangedChange
+  | DirectiveArgumentTypeChangedChange
+  | SchemaQueryTypeChangedChange
+  | SchemaMutationTypeChangedChange
+  | SchemaSubscriptionTypeChangedChange
+  | DirectiveUsageUnionMemberAddedChange
+  | DirectiveUsageUnionMemberRemovedChange
+  | DirectiveUsageEnumAddedChange
+  | DirectiveUsageEnumRemovedChange
+  | DirectiveUsageEnumValueAddedChange
+  | DirectiveUsageEnumValueRemovedChange
+  | DirectiveUsageInputObjectAddedChange
+  | DirectiveUsageInputObjectRemovedChange
+  | DirectiveUsageFieldAddedChange
+  | DirectiveUsageFieldRemovedChange
+  | DirectiveUsageScalarAddedChange
+  | DirectiveUsageScalarRemovedChange
+  | DirectiveUsageObjectAddedChange
+  | DirectiveUsageObjectRemovedChange
+  | DirectiveUsageInterfaceAddedChange
+  | DirectiveUsageInterfaceRemovedChange
+  | DirectiveUsageArgumentDefinitionAddedChange
+  | DirectiveUsageArgumentDefinitionRemovedChange
+  | DirectiveUsageSchemaAddedChange
+  | DirectiveUsageSchemaRemovedChange
+  | DirectiveUsageFieldDefinitionAddedChange
+  | DirectiveUsageFieldDefinitionRemovedChange
+  | DirectiveUsageInputFieldDefinitionAddedChange
+  | DirectiveUsageInputFieldDefinitionRemovedChange
+
+/**
+ * Type guard to check if a value is a valid Change
+ */
+export const isChange = (value: unknown): value is Change => {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'type' in value &&
+    'criticality' in value &&
+    'message' in value
+  )
+}

package/src/lib/graphql-change/criticality.ts

@@ -0,0 +1,45 @@
+import { CriticalityLevel } from '@graphql-inspector/core'
+import type { BadgeProps } from '@radix-ui/themes'
+import type { Change } from './change-types.js'
+
+export { CriticalityLevel } from '@graphql-inspector/core'
+
+// Type guard functions
+export const isCriticalityBreaking = (change: Change): boolean => change.criticality.level === CriticalityLevel.Breaking
+
+export const isCriticalityDangerous = (change: Change): boolean =>
+  change.criticality.level === CriticalityLevel.Dangerous
+
+export const isCriticalitySafe = (change: Change): boolean => change.criticality.level === CriticalityLevel.NonBreaking
+
+/** Ordered array for iteration (from most to least critical) */
+export const CRITICALITY_LEVELS = [
+  CriticalityLevel.Breaking,
+  CriticalityLevel.Dangerous,
+  CriticalityLevel.NonBreaking,
+] as const
+
+// Config for UI display
+interface CriticalityConfig {
+  color: Exclude<BadgeProps['color'], undefined>
+  label: string
+  shortLabel: string
+}
+
+export const CRITICALITY_CONFIG = {
+  [CriticalityLevel.Breaking]: {
+    color: 'red',
+    label: 'Breaking Changes',
+    shortLabel: 'Breaking',
+  },
+  [CriticalityLevel.Dangerous]: {
+    color: 'yellow',
+    label: 'Dangerous Changes',
+    shortLabel: 'Dangerous',
+  },
+  [CriticalityLevel.NonBreaking]: {
+    color: 'green',
+    label: 'Safe Changes',
+    shortLabel: 'Safe',
+  },
+} satisfies Record<CriticalityLevel, CriticalityConfig>

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

@@ -1,11 +1,13 @@
 import { GraphqlInspector } from '#dep/graphql-inspector/index'
 import type { GrafaidOld } from '#lib/grafaid-old/index'
+import type { Change } from './change-types.js'
 
-export type Change = GraphqlInspector.Core.SerializableChange & {
-  message: string
-  path?: string
-  criticality: GraphqlInspector.Core.Criticality
-}
+export * from './change-types.js'
+
+export * from './criticality.js'
+
+import * as Group from './change-groups.js'
+export { Group }
 
 export const calcChangeset = async (parameters: {
   after: GrafaidOld.Schema.Schema

package/src/lib/graphql-change/index.ts

@@ -1 +1 @@
-export * as GraphqlChange from './graphql-change.ts'
+export * as GraphqlChange from './graphql-change.js'

package/src/lib/graphql-changeset/index.ts

@@ -1 +1 @@
-export * as GraphqlChangeset from './graphql-changeset.ts'
+export * as GraphqlChangeset from './graphql-changeset.js'

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

@@ -0,0 +1,4 @@
+export * from './analysis.js'
+export * from './positioning-simple.js'
+export * from './schema-integration.js'
+export * from './types.js'

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

@@ -0,0 +1,132 @@
+import { describe, expect, it } from 'vitest'
+import { GraphQLDocument } from './$.js'
+
+describe('GraphQLDocument', () => {
+  describe('analyze', () => {
+    it('should parse a simple query and extract identifiers', () => {
+      const source = `
+        query GetUser($id: ID!) {
+          user(id: $id) {
+            name
+            email
+          }
+        }
+      `
+
+      const result = GraphQLDocument.analyze(source)
+
+      expect(result.isValid).toBe(true)
+      expect(result.identifiers.all.length).toBeGreaterThan(0)
+
+      // Should find variable
+      const variables = result.identifiers.byKind.get('Variable') || []
+      expect(variables).toHaveLength(1)
+      expect(variables[0]?.name).toBe('id')
+
+      // Should find fields
+      const fields = result.identifiers.byKind.get('Field') || []
+      expect(fields.length).toBeGreaterThan(0)
+      const fieldNames = fields.map(f => f.name)
+      expect(fieldNames).toContain('user')
+      expect(fieldNames).toContain('name')
+      expect(fieldNames).toContain('email')
+
+      // Should find types
+      const types = result.identifiers.byKind.get('Type') || []
+      expect(types.length).toBeGreaterThan(0)
+      const typeNames = types.map(t => t.name)
+      expect(typeNames).toContain('ID')
+    })
+
+    it('should handle parsing errors gracefully', () => {
+      const invalidSource = `
+        query {
+          user(id: $id {
+            name
+          }
+        }
+      `
+
+      const result = GraphQLDocument.analyze(invalidSource)
+
+      expect(result.isValid).toBe(false)
+      expect(result.identifiers.errors.length).toBeGreaterThan(0)
+    })
+
+    it('should extract context information', () => {
+      const source = `
+        query GetUserPosts($userId: ID!) {
+          user(id: $userId) {
+            posts {
+              title
+              content
+            }
+          }
+        }
+      `
+
+      const result = GraphQLDocument.analyze(source)
+
+      const fields = result.identifiers.byKind.get('Field') || []
+      const userField = fields.find(f => f.name === 'user')
+
+      expect(userField?.context.operationType).toBe('query')
+      expect(userField?.context.operationName).toBe('GetUserPosts')
+      expect(userField?.context.selectionPath).toEqual(['user'])
+    })
+
+    it('should track parent types in nested selections', () => {
+      const source = `
+        query {
+          user {
+            posts {
+              title
+            }
+          }
+        }
+      `
+
+      const result = GraphQLDocument.analyze(source)
+
+      const fields = result.identifiers.byKind.get('Field') || []
+      const titleField = fields.find(f => f.name === 'title')
+
+      expect(titleField?.schemaPath).toEqual(['Post', 'title'])
+    })
+  })
+
+  describe('extractIdentifiers', () => {
+    it('should extract identifiers with positions', () => {
+      const source = 'query { user { name } }'
+
+      const identifiers = GraphQLDocument.extractIdentifiers(source)
+
+      expect(identifiers.all.length).toBeGreaterThan(0)
+
+      // Each identifier should have position information
+      for (const identifier of identifiers.all) {
+        expect(identifier.position.start).toBeTypeOf('number')
+        expect(identifier.position.end).toBeTypeOf('number')
+        expect(identifier.position.line).toBeGreaterThan(0)
+        expect(identifier.position.column).toBeGreaterThan(0)
+      }
+    })
+
+    it('should create proper index maps', () => {
+      const source = 'query { user { name } }'
+
+      const identifiers = GraphQLDocument.extractIdentifiers(source)
+
+      // Should have position index
+      expect(identifiers.byPosition.size).toBeGreaterThan(0)
+
+      // Should have kind index
+      expect(identifiers.byKind.size).toBeGreaterThan(0)
+
+      // All identifiers should be indexed
+      for (const identifier of identifiers.all) {
+        expect(identifiers.byPosition.get(identifier.position.start)).toBe(identifier)
+      }
+    })
+  })
+})

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

@@ -0,0 +1 @@
+export * as GraphQLDocument from './graphql-document.js'

package/src/lib/graphql-document/README.md

@@ -0,0 +1,102 @@
+# GraphQL Document Component
+
+Transform static GraphQL code blocks into interactive documentation with hyperlinks, tooltips, and schema validation.
+
+## Overview
+
+The GraphQL Document component enhances markdown code blocks with:
+
+- **Hyperlinked identifiers** - Click to navigate to reference documentation
+- **Hover tooltips** - View type information and descriptions
+- **Schema validation** - Highlight errors and deprecations
+- **Build-time checking** - Catch GraphQL errors during build
+
+## Architecture
+
+The implementation follows a layered architecture:
+
+1. **Analysis Layer** - Parses GraphQL and extracts identifiers
+2. **Schema Integration** - Resolves identifiers against GraphQL schema
+3. **Positioning Engine** - Maps source positions to DOM coordinates
+4. **UI Components** - React components for interactivity
+5. **Orchestration** - Main component tying everything together
+6. **Polen Integration** - Virtual modules and Vite plugin
+
+## Usage
+
+### Basic Setup
+
+1. Import the component in your MDX files:
+
+```typescript
+import { GraphQLDocumentWithSchema } from 'polen/components'
+```
+
+2. Use the component with GraphQL documents:
+
+```mdx
+<GraphQLDocumentWithSchema>
+{`query GetUser($id: ID!) {
+  user(id: $id) {
+    name
+    email
+  }
+}`}
+</GraphQLDocumentWithSchema>
+```
+
+### Component Props
+
+The `GraphQLDocumentWithSchema` component automatically loads the schema from Polen's virtual modules. You can pass options:
+
+```mdx
+<GraphQLDocumentWithSchema 
+  options={{ 
+    debug: true,
+    onNavigate: (url) => console.log('Navigate to:', url)
+  }}
+>
+{`query { user { name } }`}
+</GraphQLDocumentWithSchema>
+```
+
+### React Component
+
+Use the component directly in React:
+
+```tsx
+import { GraphQLDocument } from 'polen/lib/graphql-document'
+
+<GraphQLDocument schema={schema} options={{ debug: true }}>
+  {`query { user { name } }`}
+</GraphQLDocument>
+```
+
+## Implementation Details
+
+### Key Components
+
+- `GraphQLDocument` - Main React component
+- `IdentifierLink` - Interactive overlay for identifiers
+- `HoverTooltip` - Tooltip showing type information
+- `GraphQLDocumentWithSchema` - Wrapper that loads schema from Polen
+- `PolenSchemaResolver` - Schema integration
+
+### Testing
+
+Run tests with:
+
+```bash
+pnpm test:unit src/lib/graphql-document
+```
+
+### Type Safety
+
+Full TypeScript support with strict typing throughout.
+
+## Future Enhancements
+
+- Code folding for large queries
+- Inline query execution
+- Schema diff visualization
+- Export to various formats