polen 0.10.0-next.9 → 0.10.0

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

@@ -0,0 +1,191 @@
+/**
+ * State management for GraphQL document tooltips
+ *
+ * Handles hover delays, pinning, and multiple tooltip coordination
+ */
+
+import { React } from '#dep/react/index'
+
+export interface TooltipState {
+  /** Currently visible tooltip (via hover) */
+  hoveredId: string | null
+  /** Set of pinned tooltip IDs */
+  pinnedIds: Set<string>
+  /** ID pending show (waiting for delay) */
+  pendingShowId: string | null
+  /** ID pending hide (waiting for grace period) */
+  pendingHideId: string | null
+}
+
+export interface UseTooltipStateOptions {
+  /** Delay before showing tooltip on hover (ms) */
+  showDelay?: number
+  /** Delay before hiding tooltip on mouse leave (ms) */
+  hideDelay?: number
+  /** Whether to allow multiple pinned tooltips */
+  allowMultiplePins?: boolean
+}
+
+export interface UseTooltipStateReturn {
+  /** Check if a tooltip should be visible */
+  isOpen: (id: string) => boolean
+  /** Check if a tooltip is pinned */
+  isPinned: (id: string) => boolean
+  /** Handle hover start */
+  onHoverStart: (id: string) => void
+  /** Handle hover end */
+  onHoverEnd: (id: string) => void
+  /** Handle click (toggle pin) */
+  onTogglePin: (id: string) => void
+  /** Handle tooltip content hover (cancels hide) */
+  onTooltipHover: (id: string) => void
+  /** Unpin a specific tooltip */
+  unpin: (id: string) => void
+  /** Unpin all tooltips */
+  unpinAll: () => void
+}
+
+export const useTooltipState = (options: UseTooltipStateOptions = {}): UseTooltipStateReturn => {
+  const {
+    showDelay = 300,
+    hideDelay = 200,
+    allowMultiplePins = true,
+  } = options
+
+  const [hoveredId, setHoveredId] = React.useState<string | null>(null)
+  const [pinnedIds, setPinnedIds] = React.useState<Set<string>>(new Set())
+  const [pendingShowId, setPendingShowId] = React.useState<string | null>(null)
+  const [pendingHideId, setPendingHideId] = React.useState<string | null>(null)
+
+  // Timer refs
+  const showTimerRef = React.useRef<NodeJS.Timeout | null>(null)
+  const hideTimerRef = React.useRef<NodeJS.Timeout | null>(null)
+
+  // Clear any pending timers
+  const clearTimers = React.useCallback(() => {
+    if (showTimerRef.current) {
+      clearTimeout(showTimerRef.current)
+      showTimerRef.current = null
+    }
+    if (hideTimerRef.current) {
+      clearTimeout(hideTimerRef.current)
+      hideTimerRef.current = null
+    }
+    setPendingShowId(null)
+    setPendingHideId(null)
+  }, [])
+
+  // Check if tooltip should be visible
+  const isOpen = React.useCallback((id: string): boolean => {
+    return hoveredId === id || pinnedIds.has(id)
+  }, [hoveredId, pinnedIds])
+
+  // Check if tooltip is pinned
+  const isPinned = React.useCallback((id: string): boolean => {
+    return pinnedIds.has(id)
+  }, [pinnedIds])
+
+  // Handle hover start
+  const onHoverStart = React.useCallback((id: string) => {
+    // Don't show if already pinned
+    if (pinnedIds.has(id)) return
+
+    // Cancel any pending hide for this ID
+    if (pendingHideId === id) {
+      clearTimeout(hideTimerRef.current!)
+      hideTimerRef.current = null
+      setPendingHideId(null)
+      return
+    }
+
+    // Clear any other pending operations
+    clearTimers()
+
+    // Schedule show
+    setPendingShowId(id)
+    showTimerRef.current = setTimeout(() => {
+      setHoveredId(id)
+      setPendingShowId(null)
+    }, showDelay)
+  }, [pinnedIds, pendingHideId, clearTimers, showDelay])
+
+  // Handle hover end
+  const onHoverEnd = React.useCallback((id: string) => {
+    // Don't hide if pinned
+    if (pinnedIds.has(id)) return
+
+    // Cancel pending show if still waiting
+    if (pendingShowId === id) {
+      clearTimeout(showTimerRef.current!)
+      showTimerRef.current = null
+      setPendingShowId(null)
+      return
+    }
+
+    // Only hide if currently showing this tooltip
+    if (hoveredId === id) {
+      setPendingHideId(id)
+      hideTimerRef.current = setTimeout(() => {
+        // First set hovered to null to trigger close animation
+        setHoveredId(null)
+        setPendingHideId(null)
+      }, hideDelay)
+    }
+  }, [pinnedIds, pendingShowId, hoveredId, hideDelay])
+
+  // Handle tooltip content hover (cancels hide)
+  const onTooltipHover = React.useCallback((id: string) => {
+    if (pendingHideId === id) {
+      clearTimeout(hideTimerRef.current!)
+      hideTimerRef.current = null
+      setPendingHideId(null)
+    }
+  }, [pendingHideId])
+
+  // Toggle pin state
+  const onTogglePin = React.useCallback((id: string) => {
+    clearTimers()
+
+    setPinnedIds((prev: Set<string>) => {
+      const next = new Set(prev)
+      if (next.has(id)) {
+        // Unpin
+        next.delete(id)
+        setHoveredId(null) // Also clear hover state
+      } else {
+        // Pin
+        if (!allowMultiplePins) {
+          next.clear() // Clear other pins
+        }
+        next.add(id)
+        setHoveredId(null) // Clear hover state since it's now pinned
+      }
+      return next
+    })
+  }, [clearTimers, allowMultiplePins])
+
+  // Unpin specific tooltip
+  const unpin = React.useCallback((id: string) => {
+    setPinnedIds((prev: Set<string>) => {
+      const next = new Set(prev)
+      next.delete(id)
+      return next
+    })
+  }, [])
+
+  // Unpin all tooltips
+  const unpinAll = React.useCallback(() => {
+    setPinnedIds(new Set())
+  }, [])
+
+  return {
+    isOpen,
+    isPinned,
+    onHoverStart,
+    onHoverEnd,
+    onTogglePin,
+    onTooltipHover,
+    unpin,
+    unpinAll,
+  }
+}

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

@@ -0,0 +1,248 @@
+/**
+ * @vitest-environment jsdom
+ */
+
+import { describe, expect, it } from 'vitest'
+import { createSimpleOverlay, createSimplePositionCalculator } from './positioning-simple.js'
+import type { Identifier } from './types.js'
+
+// 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="code-block">
+          <code>query GetUser {
+  user {
+    name
+  }
+}</code>
+        </pre>
+      `
+
+      const identifiers = [
+        createTestIdentifier('query', 1, 1),
+        createTestIdentifier('user', 2, 3, 'Field'),
+        createTestIdentifier('name', 3, 5, 'Field'),
+      ]
+
+      const codeElement = container.querySelector('code')!
+      calculator.prepareCodeBlock(codeElement, 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="code-block">
+          <code>query GetUserById($id: ID!) {</code>
+        </pre>
+      `
+
+      const identifiers = [
+        createTestIdentifier('query', 1, 1),
+        createTestIdentifier('GetUserById', 1, 7),
+        createTestIdentifier('$id', 1, 19, 'Variable'),
+        createTestIdentifier('ID', 1, 24, 'Type'),
+      ]
+
+      const codeElement = container.querySelector('code')!
+      calculator.prepareCodeBlock(codeElement, 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="code-block">
+          <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]')!
+      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="code-block">
+          <code><span data-graphql-id="existing">user</span> {</code>
+        </pre>
+      `
+
+      const identifiers = [
+        createTestIdentifier('user', 1, 1),
+      ]
+
+      const codeElement = container.querySelector('code')!
+      calculator.prepareCodeBlock(codeElement, 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="code-block">
+          <code>query {
+
+  user</code>
+        </pre>
+      `
+
+      const identifiers = [
+        createTestIdentifier('query', 1, 1),
+        createTestIdentifier('user', 3, 3),
+      ]
+
+      const codeElement = container.querySelector('code')!
+      expect(() => {
+        calculator.prepareCodeBlock(codeElement, 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')
+    })
+  })
+})

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

@@ -0,0 +1,260 @@
+/**
+ * Layer 3: Simplified Positioning & Layout Engine
+ *
+ * Maps GraphQL AST positions to DOM coordinates for overlay placement.
+ * This simplified version focuses on working with Polen's existing infrastructure.
+ */
+
+import type { Identifier } from './types.js'
+
+/**
+ * DOM position for rendering overlays
+ */
+export interface DOMPosition {
+  /** Distance from top of container in pixels */
+  top: number
+  /** Distance from left of container in pixels */
+  left: number
+  /** Width of the identifier in pixels */
+  width: number
+  /** Height of the identifier in pixels */
+  height: number
+}
+
+/**
+ * Position calculation result
+ */
+export interface PositionResult {
+  /** The calculated DOM position */
+  position: DOMPosition
+  /** The identifier this position is for */
+  identifier: Identifier
+}
+
+/**
+ * Simplified position calculator for syntax-highlighted code
+ *
+ * This version uses a more straightforward approach:
+ * 1. Find the line element by line number
+ * 2. Search for the identifier text within that line
+ * 3. Create a span around the identifier for positioning
+ *
+ * This approach modifies the DOM but is more reliable for testing
+ * and works well with React's reconciliation.
+ */
+export class SimplePositionCalculator {
+  /**
+   * Prepare a code block for positioning by wrapping identifiers in spans
+   */
+  prepareCodeBlock(
+    containerElement: Element,
+    identifiers: Identifier[],
+  ): void {
+    // Get the full text content of the container
+    const fullText = containerElement.textContent || ``
+    const lines = fullText.split(`\n`)
+
+    // Build a map of line start positions in the full text
+    const lineStartPositions: number[] = [0]
+    for (let i = 0; i < lines.length - 1; i++) {
+      const lineLength = lines[i]?.length ?? 0
+      lineStartPositions.push(lineStartPositions[i]! + lineLength + 1) // +1 for newline
+    }
+
+    // Process identifiers by line
+    for (const identifier of identifiers) {
+      const lineIndex = identifier.position.line - 1
+      if (lineIndex >= lines.length || lineIndex < 0) continue
+
+      const lineText = lines[lineIndex]
+      if (!lineText) continue
+
+      const columnIndex = identifier.position.column - 1
+
+      // Check if the identifier exists at the expected position
+      if (lineText.substring(columnIndex).startsWith(identifier.name)) {
+        // Calculate the absolute position in the full text
+        const lineStartPosition = lineStartPositions[lineIndex] ?? 0
+        const absolutePosition = lineStartPosition + columnIndex
+
+        // Check if already wrapped at this specific position
+        const existingWrapped = containerElement.querySelectorAll(`[data-graphql-id]`)
+        let alreadyWrapped = false
+        for (const wrapped of existingWrapped) {
+          if (wrapped.textContent === identifier.name) {
+            const startPos = parseInt(wrapped.getAttribute(`data-graphql-start`) || `0`)
+            if (startPos === identifier.position.start) {
+              alreadyWrapped = true
+              break
+            }
+          }
+        }
+        if (alreadyWrapped) continue
+
+        // Create wrapper span
+        const wrapper = document.createElement(`span`)
+        const id = `${identifier.position.start}-${identifier.name}-${identifier.kind}`
+        wrapper.setAttribute(`data-graphql-id`, id)
+        wrapper.setAttribute(`data-graphql-name`, identifier.name)
+        wrapper.setAttribute(`data-graphql-kind`, identifier.kind)
+        wrapper.setAttribute(`data-graphql-start`, String(identifier.position.start))
+        wrapper.setAttribute(`data-graphql-end`, String(identifier.position.end))
+        wrapper.setAttribute(`data-graphql-line`, String(identifier.position.line))
+        wrapper.setAttribute(`data-graphql-column`, String(identifier.position.column))
+        wrapper.setAttribute(`data-graphql-path`, identifier.schemaPath.join(`,`))
+
+        // Find the position in the container and wrap the text
+        const walker = document.createTreeWalker(
+          containerElement,
+          NodeFilter.SHOW_TEXT,
+          null,
+        )
+
+        let currentPos = 0
+        let node: Node | null
+
+        while (node = walker.nextNode()) {
+          const textNode = node as Text
+          const text = textNode.textContent || ``
+
+          // Check if this text node contains our identifier
+          if (currentPos <= absolutePosition && absolutePosition < currentPos + text.length) {
+            const relativePos = absolutePosition - currentPos
+
+            if (text.substring(relativePos).startsWith(identifier.name)) {
+              // Split the text node
+              const before = text.substring(0, relativePos)
+              const identifierText = identifier.name
+              const after = text.substring(relativePos + identifierText.length)
+
+              const parent = textNode.parentNode!
+
+              if (before) {
+                parent.insertBefore(document.createTextNode(before), textNode)
+              }
+
+              wrapper.textContent = identifierText
+              parent.insertBefore(wrapper, textNode)
+
+              if (after) {
+                parent.insertBefore(document.createTextNode(after), textNode)
+              }
+
+              parent.removeChild(textNode)
+              break
+            }
+          }
+
+          currentPos += text.length
+        }
+      }
+    }
+  }
+
+  /**
+   * Get positions of all wrapped identifiers
+   */
+  getIdentifierPositions(
+    containerElement: Element,
+    relativeToElement?: Element,
+  ): Map<string, PositionResult> {
+    const results = new Map<string, PositionResult>()
+
+    // Find all wrapped identifiers
+    const wrappedIdentifiers = containerElement.querySelectorAll(`[data-graphql-id]`)
+
+    // Use the provided element for relative positioning, or the container itself
+    const referenceElement = relativeToElement || containerElement
+
+    for (const element of wrappedIdentifiers) {
+      const id = element.getAttribute(`data-graphql-id`)
+      if (!id) continue
+
+      // Get position relative to the reference element
+      const referenceRect = referenceElement.getBoundingClientRect()
+      const elementRect = element.getBoundingClientRect()
+
+      const position: DOMPosition = {
+        top: elementRect.top - referenceRect.top,
+        left: elementRect.left - referenceRect.left,
+        width: elementRect.width,
+        height: elementRect.height,
+      }
+
+      // Reconstruct identifier from data attributes
+      const identifier: Identifier = {
+        name: element.getAttribute(`data-graphql-name`) || ``,
+        kind: (element.getAttribute(`data-graphql-kind`) || `Field`) as Identifier[`kind`],
+        position: {
+          start: parseInt(element.getAttribute(`data-graphql-start`) || `0`),
+          end: parseInt(element.getAttribute(`data-graphql-end`) || `0`),
+          line: parseInt(element.getAttribute(`data-graphql-line`) || `1`),
+          column: parseInt(element.getAttribute(`data-graphql-column`) || `1`),
+        },
+        schemaPath: (element.getAttribute(`data-graphql-path`) || ``).split(`,`).filter(Boolean),
+        context: { selectionPath: [] },
+      }
+
+      results.set(id, { position, identifier })
+    }
+
+    return results
+  }
+}
+
+/**
+ * Create invisible overlay for a position
+ */
+export const createSimpleOverlay = (
+  position: DOMPosition,
+  identifier: Identifier,
+  options?: {
+    onClick?: (identifier: Identifier) => void
+    onHover?: (identifier: Identifier, event: MouseEvent) => void
+    className?: string
+  },
+): HTMLElement => {
+  const overlay = document.createElement(`div`)
+
+  // Base styles for positioning
+  overlay.style.position = `absolute`
+  overlay.style.top = `${position.top}px`
+  overlay.style.left = `${position.left}px`
+  overlay.style.width = `${position.width}px`
+  overlay.style.height = `${position.height}px`
+  overlay.style.cursor = `pointer`
+  overlay.style.zIndex = `10`
+
+  // Add custom class if provided
+  if (options?.className) {
+    overlay.className = options.className
+  }
+
+  // Data attributes
+  overlay.setAttribute(`data-graphql-overlay`, `true`)
+  overlay.setAttribute(`data-graphql-name`, identifier.name)
+  overlay.setAttribute(`data-graphql-kind`, identifier.kind)
+
+  // Event handlers
+  if (options?.onClick) {
+    overlay.addEventListener(`click`, (e) => {
+      e.preventDefault()
+      options.onClick!(identifier)
+    })
+  }
+
+  if (options?.onHover) {
+    overlay.addEventListener(`mouseenter`, (e) => {
+      options.onHover!(identifier, e)
+    })
+  }
+
+  return overlay
+}
+
+/**
+ * Factory function for position calculator
+ */
+export const createSimplePositionCalculator = (): SimplePositionCalculator => {
+  return new SimplePositionCalculator()
+}