polen 0.10.0-next.8 → 0.10.0

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

@@ -0,0 +1,144 @@
+/**
+ * Minimal styles for GraphQL Document interactive code blocks
+ */
+
+export const graphqlDocumentStyles = `
+/* Container styles */
+.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;
+}
+
+/* Identifier overlay styles */
+.graphql-identifier-overlay {
+  transition: background-color 0.2s ease;
+}
+
+/* Clickable identifiers get visual feedback */
+.graphql-identifier-overlay.graphql-clickable {
+  /* Subtle underline effect using box-shadow to not affect layout */
+  box-shadow: 0 1px 0 0 rgba(var(--accent-9), 0.3);
+  transition: box-shadow 0.2s ease, background-color 0.2s ease;
+}
+
+.graphql-identifier-overlay.graphql-clickable:hover {
+  background-color: rgba(var(--accent-3), 0.5);
+  box-shadow: 0 1px 0 0 rgba(var(--accent-9), 0.6);
+}
+
+/* Active/open state */
+.graphql-identifier-overlay.graphql-tooltip-open {
+  background-color: rgba(var(--accent-3), 0.5);
+  box-shadow: 0 1px 0 0 var(--accent-9);
+}
+
+/* Error state */
+.graphql-identifier-overlay.graphql-error {
+  box-shadow: 0 1.5px 0 0 var(--red-9);
+}
+
+.graphql-identifier-overlay.graphql-error:hover {
+  background-color: rgba(var(--red-3), 0.5);
+}
+
+/* Deprecated state */
+.graphql-identifier-overlay.graphql-deprecated {
+  text-decoration: line-through;
+  opacity: 0.7;
+}
+
+/* Debug mode */
+.graphql-identifier-overlay.graphql-debug {
+  background-color: rgba(59, 130, 246, 0.1) !important;
+  border: 1px solid rgba(59, 130, 246, 0.3) !important;
+}
+
+/* Kind-specific colors */
+.graphql-identifier-overlay.graphql-type.graphql-clickable {
+  box-shadow: 0 1px 0 0 rgba(var(--blue-9), 0.3);
+}
+
+.graphql-identifier-overlay.graphql-field.graphql-clickable {
+  box-shadow: 0 1px 0 0 rgba(var(--green-9), 0.3);
+}
+
+.graphql-identifier-overlay.graphql-argument.graphql-clickable {
+  box-shadow: 0 1px 0 0 rgba(var(--orange-9), 0.3);
+}
+
+.graphql-identifier-overlay.graphql-variable {
+  box-shadow: 0 1px 0 0 rgba(var(--purple-9), 0.3);
+}
+
+.graphql-identifier-overlay.graphql-directive.graphql-clickable {
+  box-shadow: 0 1px 0 0 rgba(var(--amber-9), 0.3);
+}
+
+/* Popover animation */
+.graphql-identifier-popover {
+  animation: graphql-popover-show 150ms ease-out;
+}
+
+@keyframes graphql-popover-show {
+  from {
+    opacity: 0;
+    transform: translateY(2px);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
+/* Validation errors */
+.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;
+}
+
+/* Loading state */
+.graphql-document.graphql-loading {
+  opacity: 0.6;
+  pointer-events: none;
+}
+
+.graphql-document.graphql-loading::after {
+  content: '';
+  position: absolute;
+  top: 50%;
+  left: 50%;
+  width: 20px;
+  height: 20px;
+  margin: -10px 0 0 -10px;
+  border: 2px solid var(--gray-6);
+  border-top-color: var(--accent-9);
+  border-radius: 50%;
+  animation: graphql-spinner 0.8s linear infinite;
+}
+
+@keyframes graphql-spinner {
+  to {
+    transform: rotate(360deg);
+  }
+}`

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

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

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
+- **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 './$.js'
+
+// Example GraphQL query with various constructs
+const exampleQuery = `
+  query GetUserWithProjects($id: ID!, $limit: Int = 10) {
+    user(id: $id) {
+      name
+      projects(first: $limit) {
+        name
+        isPrivate
+        owner {
+          name
+        }
+      }
+      ... on EnterpriseUser {
+        organization
+      }
+    }
+  }
+
+  fragment UserBasics on User {
+    name
+    email
+    role
+  }
+`
+
+/**
+ * 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
+const 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.js'
+export * from './components/index.js'
+export * from './positioning-simple.js'
+export * from './schema-integration.js'
+export * from './types.js'
+
+// Re-export key functions for convenience
+export { analyze, analyzer, extractIdentifiers } from './analysis.js'
+export { GraphQLDocument } from './components/GraphQLDocument.js'
+export { createSimpleOverlay, createSimplePositionCalculator } from './positioning-simple.js'
+export { analyzeWithSchema, createPolenSchemaResolver } from './schema-integration.js'

package/src/lib/graphql-document/hooks/use-tooltip-state.test.ts

@@ -0,0 +1,76 @@
+/**
+ * Unit tests for tooltip state management hook
+ *
+ * @vitest-environment jsdom
+ */
+
+import { act, renderHook } from '@testing-library/react'
+import { describe, expect, it, vi } from 'vitest'
+import { useTooltipState } from './use-tooltip-state.js'
+
+describe('useTooltipState', () => {
+  it('shows tooltip after hover delay', () => {
+    vi.useFakeTimers()
+    const { result } = renderHook(() => useTooltipState({ showDelay: 300 }))
+
+    act(() => {
+      result.current.onHoverStart('field-1')
+    })
+    expect(result.current.isOpen('field-1')).toBe(false)
+
+    act(() => {
+      vi.advanceTimersByTime(300)
+    })
+    expect(result.current.isOpen('field-1')).toBe(true)
+    vi.useRealTimers()
+  })
+
+  it('hides tooltip after hover end delay', () => {
+    vi.useFakeTimers()
+    const { result } = renderHook(() => useTooltipState())
+
+    // Show tooltip
+    act(() => {
+      result.current.onHoverStart('field-1')
+      vi.advanceTimersByTime(300)
+    })
+
+    // Trigger hide
+    act(() => {
+      result.current.onHoverEnd('field-1')
+    })
+    expect(result.current.isOpen('field-1')).toBe(true) // Still open during delay
+
+    act(() => {
+      vi.advanceTimersByTime(200)
+    })
+    expect(result.current.isOpen('field-1')).toBe(false)
+    vi.useRealTimers()
+  })
+
+  it('pins and unpins tooltip on toggle', () => {
+    const { result } = renderHook(() => useTooltipState())
+
+    act(() => {
+      result.current.onTogglePin('field-1')
+    })
+    expect(result.current.isPinned('field-1')).toBe(true)
+
+    act(() => {
+      result.current.onTogglePin('field-1')
+    })
+    expect(result.current.isPinned('field-1')).toBe(false)
+  })
+
+  it('allows multiple pins when enabled', () => {
+    const { result } = renderHook(() => useTooltipState())
+
+    act(() => {
+      result.current.onTogglePin('field-1')
+      result.current.onTogglePin('field-2')
+    })
+
+    expect(result.current.isPinned('field-1')).toBe(true)
+    expect(result.current.isPinned('field-2')).toBe(true)
+  })
+})