polen 0.10.0-next.10 → 0.10.0-next.12

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

@@ -0,0 +1,221 @@
+import type { React } from '#dep/react/index'
+import { useState } from 'react'
+import type { DOMPosition } from '../positioning-simple.ts'
+import type { SchemaResolution } from '../schema-integration.ts'
+import type { Identifier } from '../types.ts'
+import { HoverTooltip } from './HoverTooltip.tsx'
+
+/**
+ * Props for the IdentifierLink component
+ */
+export interface IdentifierLinkProps {
+  /** The GraphQL identifier */
+  identifier: Identifier
+  /** Schema resolution information */
+  resolution: SchemaResolution
+  /** DOM position for overlay placement */
+  position: DOMPosition
+  /** Navigation handler */
+  onNavigate: (url: string) => void
+  /** Whether to show debug visuals */
+  debug?: boolean
+  /** Whether this tooltip is open */
+  isOpen?: boolean
+  /** Toggle tooltip open state */
+  onToggle?: (open: boolean) => void
+}
+
+/**
+ * Interactive overlay for a GraphQL identifier
+ *
+ * Renders an invisible clickable area over the identifier text
+ * with hover tooltips and navigation to schema reference pages.
+ */
+export const IdentifierLink: React.FC<IdentifierLinkProps> = ({
+  identifier,
+  resolution,
+  position,
+  onNavigate,
+  debug = false,
+  isOpen = false,
+  onToggle,
+}) => {
+  const [isHovered, setIsHovered] = useState(false)
+
+  // Use external state if provided, otherwise manage locally
+  const showTooltip = isOpen
+  const setShowTooltip = (show: boolean) => {
+    onToggle?.(show)
+  }
+
+  // Determine visual state
+  const isClickable = resolution.exists
+  const hasError = !resolution.exists && (identifier.kind === 'Type' || identifier.kind === 'Field')
+  const isDeprecated = !!resolution.deprecated
+
+  // Build class names
+  const classNames = [
+    'graphql-identifier-overlay',
+    `graphql-${identifier.kind.toLowerCase()}`,
+    isClickable && 'graphql-clickable',
+    hasError && 'graphql-error',
+    isDeprecated && 'graphql-deprecated',
+    isHovered && 'graphql-hovered',
+    showTooltip && 'graphql-tooltip-open',
+    debug && 'graphql-debug',
+  ].filter(Boolean).join(' ')
+
+  const handleClick = (e: React.MouseEvent) => {
+    e.preventDefault()
+    e.stopPropagation()
+
+    // Toggle tooltip on click
+    setShowTooltip(!showTooltip)
+  }
+
+  const handleNavigate = (e: React.MouseEvent) => {
+    e.preventDefault()
+    e.stopPropagation()
+    if (isClickable) {
+      onNavigate(resolution.referenceUrl)
+    }
+  }
+
+  return (
+    <>
+      {isClickable
+        ? (
+          <a
+            href={resolution.referenceUrl}
+            className={classNames + ' graphql-identifier-link'}
+            style={{
+              position: 'absolute',
+              top: position.top,
+              left: position.left,
+              width: position.width,
+              height: position.height,
+              cursor: 'pointer',
+              zIndex: 10,
+              pointerEvents: 'auto',
+              display: 'block',
+              textDecoration: 'none',
+              // Debug mode visual
+              ...(debug && {
+                backgroundColor: hasError ? 'rgba(239, 68, 68, 0.1)' : 'rgba(59, 130, 246, 0.1)',
+                border: `1px solid ${hasError ? 'rgba(239, 68, 68, 0.3)' : 'rgba(59, 130, 246, 0.3)'}`,
+              }),
+            }}
+            onClick={handleClick}
+            onMouseEnter={() => setIsHovered(true)}
+            onMouseLeave={() => setIsHovered(false)}
+            aria-label={`${identifier.kind} ${identifier.name} - Click to view documentation`}
+            data-graphql-identifier={identifier.name}
+            data-graphql-kind={identifier.kind}
+          />
+        )
+        : (
+          <div
+            className={classNames}
+            style={{
+              position: 'absolute',
+              top: position.top,
+              left: position.left,
+              width: position.width,
+              height: position.height,
+              cursor: 'pointer', // Make it clickable even for errors
+              zIndex: 10,
+              pointerEvents: 'auto',
+              // Debug mode visual
+              ...(debug && {
+                backgroundColor: 'rgba(239, 68, 68, 0.1)',
+                border: `1px solid rgba(239, 68, 68, 0.3)`,
+              }),
+            }}
+            onClick={handleClick} // Add click handler for errors too
+            onMouseEnter={() => setIsHovered(true)}
+            onMouseLeave={() => setIsHovered(false)}
+            role='button'
+            aria-label={`${identifier.kind} ${identifier.name} - Click to view information`}
+            data-graphql-identifier={identifier.name}
+            data-graphql-kind={identifier.kind}
+          />
+        )}
+
+      {/* Tooltip - show on click, not hover */}
+      {showTooltip && (
+        <HoverTooltip
+          identifier={identifier}
+          documentation={resolution.documentation || {
+            description: hasError
+              ? `${identifier.kind} "${identifier.name}" not found in schema. This ${identifier.kind.toLowerCase()} does not exist in the current GraphQL schema.`
+              : `${identifier.kind}: ${identifier.name}`,
+            typeInfo: identifier.kind,
+          }}
+          position={position}
+          hasError={hasError}
+          referenceUrl={resolution.referenceUrl}
+          onClose={() => setShowTooltip(false)}
+          onNavigate={isClickable ? () => onNavigate(resolution.referenceUrl) : undefined}
+        />
+      )}
+    </>
+  )
+}
+
+/**
+ * Default styles for identifier overlays
+ *
+ * These can be included in the document or overridden by custom styles.
+ */
+export const identifierLinkStyles = `
+.graphql-identifier-overlay {
+  /* Base styles for all overlays */
+  transition: background-color 0.2s ease;
+}
+
+.graphql-identifier-overlay.graphql-clickable:hover {
+  /* Subtle highlight on hover for clickable identifiers */
+  background-color: rgba(59, 130, 246, 0.05);
+}
+
+.graphql-identifier-overlay.graphql-error {
+  /* Error indicator */
+  border-bottom: 2px wavy red;
+}
+
+.graphql-identifier-overlay.graphql-deprecated {
+  /* Deprecated indicator */
+  text-decoration: line-through;
+  opacity: 0.7;
+}
+
+.graphql-identifier-overlay.graphql-debug {
+  /* Debug mode makes overlays visible */
+  background-color: rgba(59, 130, 246, 0.1) !important;
+  border: 1px solid rgba(59, 130, 246, 0.3) !important;
+}
+
+/* Kind-specific styles */
+.graphql-identifier-overlay.graphql-type {
+  /* Type identifiers */
+}
+
+.graphql-identifier-overlay.graphql-field {
+  /* Field identifiers */
+}
+
+.graphql-identifier-overlay.graphql-argument {
+  /* Argument identifiers */
+  font-style: italic;
+}
+
+.graphql-identifier-overlay.graphql-variable {
+  /* Variable identifiers */
+  color: var(--purple-11);
+}
+
+.graphql-identifier-overlay.graphql-directive {
+  /* Directive identifiers */
+  color: var(--amber-11);
+}
+`

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

@@ -0,0 +1,4 @@
+export * from './GraphQLDocument.tsx'
+export * from './GraphQLDocumentWithSchema.tsx'
+export * from './HoverTooltip.tsx'
+export * from './IdentifierLink.tsx'

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

@@ -0,0 +1,155 @@
+# GraphQL Document Component Demo
+
+This page demonstrates the interactive GraphQL Document component that transforms static code blocks into rich, interactive documentation.
+
+## Basic Query Example
+
+Hover over the identifiers below to see type information and documentation. Click on types and fields to navigate to their reference pages.
+
+```graphql
+query GetUser($id: ID!) {
+  user(id: $id) {
+    id
+    name
+    email
+    posts(first: 10) {
+      id
+      title
+      content
+      author {
+        name
+      }
+    }
+  }
+}
+```
+
+## Mutation Example
+
+This mutation creates a new post. Notice how the component provides information about input types and return values.
+
+```graphql
+mutation CreatePost($input: CreatePostInput!) {
+  createPost(input: $input) {
+    id
+    title
+    content
+    createdAt
+    author {
+      id
+      name
+    }
+  }
+}
+```
+
+## Subscription Example
+
+Subscriptions work the same way - all GraphQL operations are fully interactive.
+
+```graphql
+subscription OnCommentAdded($postId: ID!) {
+  commentAdded(postId: $postId) {
+    id
+    content
+    author {
+      name
+      avatar
+    }
+    createdAt
+  }
+}
+```
+
+## Fragment Example
+
+Fragments are also supported with full type information and navigation.
+
+```graphql
+fragment UserInfo on User {
+  id
+  name
+  email
+  profile {
+    bio
+    avatar
+    website
+  }
+}
+
+query GetUserWithFragment($id: ID!) {
+  user(id: $id) {
+    ...UserInfo
+    posts {
+      id
+      title
+    }
+  }
+}
+```
+
+## Error Handling
+
+The component validates GraphQL against the schema and highlights errors. Try hovering over the invalid field below:
+
+```graphql
+query InvalidQuery {
+  user {
+    nonExistentField
+    name
+  }
+}
+```
+
+## Plain Mode
+
+Sometimes you want to show GraphQL without interactivity. Use the `plain` option:
+
+```graphql plain
+query SimpleQuery {
+  users {
+    name
+  }
+}
+```
+
+## Debug Mode
+
+Enable debug mode to see the overlay boundaries:
+
+```graphql debug
+query DebugExample {
+  user {
+    id
+    name
+  }
+}
+```
+
+## Features
+
+The GraphQL Document component provides:
+
+- **Interactive Navigation**: Click on any type or field to navigate to its reference documentation
+- **Hover Tooltips**: See type information, descriptions, and deprecation warnings
+- **Schema Validation**: Invalid queries are highlighted with error messages
+- **Syntax Highlighting**: Beautiful syntax highlighting with Shiki
+- **Smart Positioning**: Tooltips automatically position themselves to stay within the viewport
+- **Accessibility**: Full keyboard navigation and screen reader support
+
+## Configuration Options
+
+```graphql validate=false
+# This query won't be validated at build time
+query {
+  anything {
+    goes
+  }
+}
+```
+
+Available options:
+
+- `plain` - Disable all interactive features
+- `debug` - Show overlay boundaries for debugging
+- `validate=false` - Skip validation for this block

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'