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

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

@@ -0,0 +1,282 @@
+import type { React } from '#dep/react/index'
+import { Badge, Box, Card, Flex, Text } from '@radix-ui/themes'
+import { useEffect, useRef, useState } from 'react'
+import type { DOMPosition } from '../positioning-simple.ts'
+import type { Documentation } from '../schema-integration.ts'
+import type { Identifier } from '../types.ts'
+
+/**
+ * Props for the HoverTooltip component
+ */
+export interface HoverTooltipProps {
+  /** The identifier being hovered */
+  identifier: Identifier
+  /** Documentation from schema */
+  documentation: Documentation
+  /** Position of the identifier */
+  position: DOMPosition
+  /** Whether this identifier has an error */
+  hasError?: boolean
+  /** Reference URL for "View docs" link */
+  referenceUrl: string
+  /** Callback to close the tooltip */
+  onClose?: () => void
+  /** Callback to navigate to docs */
+  onNavigate?: () => void
+}
+
+/**
+ * Tooltip shown on hover over GraphQL identifiers
+ *
+ * Displays type information, descriptions, deprecation warnings,
+ * and links to full documentation.
+ */
+export const HoverTooltip: React.FC<HoverTooltipProps> = ({
+  identifier,
+  documentation,
+  position,
+  hasError = false,
+  referenceUrl,
+  onClose,
+  onNavigate,
+}) => {
+  const tooltipRef = useRef<HTMLDivElement>(null)
+  const [tooltipPosition, setTooltipPosition] = useState({ top: 0, left: 0 })
+
+  // Calculate tooltip position to avoid viewport edges
+  useEffect(() => {
+    if (!tooltipRef.current) return
+
+    const tooltip = tooltipRef.current
+    const rect = tooltip.getBoundingClientRect()
+    const viewportWidth = window.innerWidth
+    const viewportHeight = window.innerHeight
+
+    // Default position: above the identifier
+    let top = position.top - rect.height - 8
+    let left = position.left
+
+    // Adjust if tooltip would go off screen
+    if (top < 0) {
+      // Show below if not enough space above
+      top = position.top + position.height + 8
+    }
+
+    if (left + rect.width > viewportWidth) {
+      // Align right edge with identifier if too wide
+      left = position.left + position.width - rect.width
+    }
+
+    if (left < 0) {
+      // Keep on screen
+      left = 8
+    }
+
+    setTooltipPosition({ top, left })
+  }, [position])
+
+  // 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 (
+    <div
+      ref={tooltipRef}
+      className='graphql-hover-tooltip'
+      style={{
+        position: 'absolute',
+        top: tooltipPosition.top,
+        left: tooltipPosition.left,
+        zIndex: 100,
+        maxWidth: '400px',
+        pointerEvents: 'auto', // Make tooltip interactive
+      }}
+    >
+      <Card size='2' variant='surface'>
+        <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>
+            {onClose && (
+              <button
+                onClick={onClose}
+                style={{
+                  background: 'none',
+                  border: 'none',
+                  cursor: 'pointer',
+                  padding: '4px',
+                  color: 'var(--gray-11)',
+                  fontSize: '18px',
+                  lineHeight: '1',
+                  fontWeight: 'bold',
+                  borderRadius: '4px',
+                  transition: 'background-color 0.2s',
+                }}
+                onMouseEnter={(e) => {
+                  e.currentTarget.style.backgroundColor = 'var(--gray-a3)'
+                }}
+                onMouseLeave={(e) => {
+                  e.currentTarget.style.backgroundColor = 'transparent'
+                }}
+                aria-label='Close tooltip'
+              >
+                ×
+              </button>
+            )}
+          </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 && (
+            <Box>
+              <Text size='1'>
+                <a
+                  href={referenceUrl}
+                  onClick={(e) => {
+                    e.preventDefault()
+                    onNavigate()
+                    onClose?.()
+                  }}
+                  style={{
+                    color: 'var(--accent-9)',
+                    textDecoration: 'none',
+                    borderBottom: '1px solid transparent',
+                    transition: 'border-color 0.2s',
+                    cursor: 'pointer',
+                  }}
+                  onMouseEnter={(e) => {
+                    e.currentTarget.style.borderBottomColor = 'var(--accent-9)'
+                  }}
+                  onMouseLeave={(e) => {
+                    e.currentTarget.style.borderBottomColor = 'transparent'
+                  }}
+                >
+                  View full documentation →
+                </a>
+              </Text>
+            </Box>
+          )}
+        </Flex>
+      </Card>
+    </div>
+  )
+}
+
+/**
+ * Default styles for hover tooltips
+ */
+export const hoverTooltipStyles = `
+.graphql-hover-tooltip {
+  /* Tooltip animation */
+  animation: graphql-tooltip-fade-in 0.2s ease-out;
+}
+
+@keyframes graphql-tooltip-fade-in {
+  from {
+    opacity: 0;
+    transform: translateY(4px);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
+/* Ensure tooltips appear above other content */
+.graphql-hover-tooltip .rt-Card {
+  box-shadow: 0 10px 38px -10px rgba(22, 23, 24, 0.35), 
+              0 10px 20px -15px rgba(22, 23, 24, 0.2);
+}
+`

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