polen 0.10.0-next.21 → 0.10.0-next.23

package/src/template/components/GraphQLInteractive/hooks/use-popover-state.ts

@@ -0,0 +1,244 @@
+/**
+ * State management for GraphQL token popovers
+ *
+ * Handles hover delays, pinning, and multiple popover coordination
+ */
+
+import { React as ReactHooks } from '#dep/react/index'
+
+export interface PopoverState {
+  /** Currently visible popover (via hover) */
+  hoveredId: string | null
+  /** Set of pinned popover 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 UsePopoverStateOptions {
+  /** Delay before showing popover on hover (ms) */
+  showDelay?: number
+  /** Delay before hiding popover on mouse leave (ms) */
+  hideDelay?: number
+  /** Whether to allow multiple pinned popovers */
+  allowMultiplePins?: boolean
+}
+
+export interface UsePopoverStateReturn {
+  /** Check if a popover should be visible */
+  isOpen: (id: string) => boolean
+  /** Check if a popover 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 popover content hover (cancels hide) */
+  onPopoverHover: (id: string) => void
+  /** Handle popover content leave (starts hide timer) */
+  onPopoverLeave: (id: string) => void
+  /** Unpin a specific popover */
+  unpin: (id: string) => void
+  /** Unpin all popovers */
+  unpinAll: () => void
+}
+
+export const usePopoverState = (options: UsePopoverStateOptions = {}): UsePopoverStateReturn => {
+  const {
+    showDelay = 300,
+    hideDelay = 200,
+    allowMultiplePins = true,
+  } = options
+
+  const [hoveredId, setHoveredId] = ReactHooks.useState<string | null>(null)
+  const [pinnedIds, setPinnedIds] = ReactHooks.useState<Set<string>>(new Set())
+  const [pendingShowId, setPendingShowId] = ReactHooks.useState<string | null>(null)
+  const [pendingHideId, setPendingHideId] = ReactHooks.useState<string | null>(null)
+
+  // Timer refs
+  const showTimerRef = ReactHooks.useRef<NodeJS.Timeout | null>(null)
+  const hideTimerRef = ReactHooks.useRef<NodeJS.Timeout | null>(null)
+
+  // Clear any pending timers
+  const clearTimers = ReactHooks.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 popover should be visible
+  const isOpen = ReactHooks.useCallback((id: string): boolean => {
+    return hoveredId === id || pinnedIds.has(id)
+  }, [hoveredId, pinnedIds])
+
+  // Check if popover is pinned
+  const isPinned = ReactHooks.useCallback((id: string): boolean => {
+    return pinnedIds.has(id)
+  }, [pinnedIds])
+
+  // Handle hover start
+  const onHoverStart = ReactHooks.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 existing timers
+    clearTimers()
+
+    // Set pending show
+    setPendingShowId(id)
+
+    // Start show timer
+    showTimerRef.current = setTimeout(() => {
+      setHoveredId(id)
+      setPendingShowId(null)
+      showTimerRef.current = null
+    }, showDelay)
+  }, [pinnedIds, pendingHideId, clearTimers, showDelay])
+
+  // Handle hover end
+  const onHoverEnd = ReactHooks.useCallback((id: string) => {
+    // Don't hide if pinned
+    if (pinnedIds.has(id)) return
+
+    // Cancel any pending show
+    if (pendingShowId === id) {
+      clearTimeout(showTimerRef.current!)
+      showTimerRef.current = null
+      setPendingShowId(null)
+      return
+    }
+
+    // Only hide if currently hovered
+    if (hoveredId === id) {
+      setPendingHideId(id)
+
+      hideTimerRef.current = setTimeout(() => {
+        setHoveredId(null)
+        setPendingHideId(null)
+        hideTimerRef.current = null
+      }, hideDelay)
+    }
+  }, [pinnedIds, pendingShowId, hoveredId, hideDelay])
+
+  // Handle popover content hover (cancels hide)
+  const onPopoverHover = ReactHooks.useCallback((id: string) => {
+    if (pendingHideId === id) {
+      clearTimeout(hideTimerRef.current!)
+      hideTimerRef.current = null
+      setPendingHideId(null)
+    }
+  }, [pendingHideId])
+
+  // Handle popover content leave (starts hide timer)
+  const onPopoverLeave = ReactHooks.useCallback((id: string) => {
+    // Don't hide if pinned
+    if (pinnedIds.has(id)) return
+
+    // Only hide if currently hovered
+    if (hoveredId === id) {
+      setPendingHideId(id)
+
+      hideTimerRef.current = setTimeout(() => {
+        setHoveredId(null)
+        setPendingHideId(null)
+        hideTimerRef.current = null
+      }, hideDelay)
+    }
+  }, [pinnedIds, hoveredId, hideDelay])
+
+  // Toggle pin state
+  const onTogglePin = ReactHooks.useCallback((id: string) => {
+    setPinnedIds(prev => {
+      const next = new Set(prev)
+
+      if (next.has(id)) {
+        // Unpin
+        next.delete(id)
+      } else {
+        // Pin
+        if (!allowMultiplePins) {
+          // Clear other pins if multiple not allowed
+          next.clear()
+        }
+        next.add(id)
+
+        // Clear any hover state for this ID
+        if (hoveredId === id) {
+          setHoveredId(null)
+        }
+
+        // Clear any pending operations
+        if (pendingShowId === id) {
+          clearTimeout(showTimerRef.current!)
+          showTimerRef.current = null
+          setPendingShowId(null)
+        }
+        if (pendingHideId === id) {
+          clearTimeout(hideTimerRef.current!)
+          hideTimerRef.current = null
+          setPendingHideId(null)
+        }
+      }
+
+      return next
+    })
+  }, [allowMultiplePins, hoveredId, pendingShowId, pendingHideId])
+
+  // Unpin specific popover
+  const unpin = ReactHooks.useCallback((id: string) => {
+    setPinnedIds(prev => {
+      const next = new Set(prev)
+      next.delete(id)
+      return next
+    })
+  }, [])
+
+  // Unpin all popovers
+  const unpinAll = ReactHooks.useCallback(() => {
+    setPinnedIds(new Set())
+  }, [])
+
+  // Cleanup timers on unmount and when dependencies change
+  ReactHooks.useEffect(() => {
+    return () => {
+      if (showTimerRef.current) clearTimeout(showTimerRef.current)
+      if (hideTimerRef.current) clearTimeout(hideTimerRef.current)
+    }
+  }, [])
+
+  // Clear timers when delay options change to prevent stale timers
+  ReactHooks.useEffect(() => {
+    clearTimers()
+  }, [showDelay, hideDelay, clearTimers])
+
+  return {
+    isOpen,
+    isPinned,
+    onHoverStart,
+    onHoverEnd,
+    onTogglePin,
+    onPopoverHover,
+    onPopoverLeave,
+    unpin,
+    unpinAll,
+  }
+}

package/src/template/components/GraphQLInteractive/index.ts

@@ -0,0 +1 @@
+export { GraphQLInteractive } from './GraphQLInteractive.js'

package/src/template/components/GraphQLInteractive/lib/graphql-node-types.ts

@@ -0,0 +1,217 @@
+/**
+ * Tree-sitter GraphQL Grammar Node Types
+ *
+ * This file defines all possible node types from the tree-sitter-graphql grammar.
+ * These types are used by the tree-sitter parser when parsing GraphQL documents.
+ *
+ * Source: https://github.com/bkegley/tree-sitter-graphql
+ *
+ * Having these as a TypeScript union type enables:
+ * - Type-safe node.type checking
+ * - IntelliSense/autocomplete in IDEs
+ * - Compile-time verification of node type strings
+ * - Better code maintainability and refactoring
+ */
+
+/**
+ * All possible node types that can be returned by tree-sitter-graphql
+ * when parsing GraphQL documents.
+ */
+export type TreeSitterGraphQLNodeType =
+  // Structure
+  | 'document'
+  | 'definition'
+  | 'executable_definition'
+  | 'type_system_definition'
+  | 'type_system_extension'
+  | 'source_file'
+  // Operations
+  | 'operation_definition'
+  | 'selection_set'
+  | 'selection'
+  | 'field'
+  | 'alias'
+  // Fragments
+  | 'fragment_definition'
+  | 'fragment_spread'
+  | 'inline_fragment'
+  | 'fragment_name'
+  | 'type_condition'
+  // Arguments and Variables
+  | 'arguments'
+  | 'argument'
+  | 'variable'
+  | 'variable_definition'
+  | 'variable_definitions'
+  | 'default_value'
+  // Types
+  | 'type'
+  | 'named_type'
+  | 'list_type'
+  | 'non_null_type'
+  // Type Definitions
+  | 'type_definition'
+  | 'scalar_type_definition'
+  | 'object_type_definition'
+  | 'interface_type_definition'
+  | 'union_type_definition'
+  | 'enum_type_definition'
+  | 'input_object_type_definition'
+  // Type Extensions
+  | 'type_extension'
+  | 'scalar_type_extension'
+  | 'object_type_extension'
+  | 'interface_type_extension'
+  | 'union_type_extension'
+  | 'enum_type_extension'
+  | 'input_object_type_extension'
+  // Schema
+  | 'schema_definition'
+  | 'schema_extension'
+  | 'root_operation_type_definition'
+  // Field Definitions
+  | 'fields_definition'
+  | 'field_definition'
+  | 'arguments_definition'
+  | 'input_value_definition'
+  | 'input_fields_definition'
+  // Directives
+  | 'directives'
+  | 'directive'
+  | 'directive_definition'
+  | 'directive_locations'
+  | 'directive_location'
+  // Enum
+  | 'enum_values_definition'
+  | 'enum_value_definition'
+  | 'enum_value'
+  // Other Type System
+  | 'implements_interfaces'
+  | 'union_member_types'
+  | 'description'
+  // Values
+  | 'value'
+  | 'string_value'
+  | 'int_value'
+  | 'float_value'
+  | 'boolean_value'
+  | 'null_value'
+  | 'list_value'
+  | 'object_value'
+  | 'object_field'
+  // Basic tokens
+  | 'name'
+  | 'comment'
+  | 'comma'
+  // Punctuation tokens (anonymous nodes in the grammar)
+  | '{'
+  | '}'
+  | '('
+  | ')'
+  | '['
+  | ']'
+  | ':'
+  | '='
+  | ','
+  | '!'
+  | '|'
+  | '&'
+  | '@'
+  | '...'
+  | '$'
+  // GraphQL Keywords (these are also node types)
+  | 'query'
+  | 'mutation'
+  | 'subscription'
+  | 'fragment'
+  | 'on'
+  | 'type'
+  | 'interface'
+  | 'enum'
+  | 'scalar'
+  | 'union'
+  | 'input'
+  | 'schema'
+  | 'directive'
+  | 'implements'
+  | 'extend'
+  | 'true'
+  | 'false'
+  | 'null'
+  // Custom synthetic nodes
+  | 'error_hint'
+  | 'whitespace'
+
+/**
+ * Subset of node types that are interactive in Polen's GraphQL viewer
+ */
+export type InteractiveNodeParentType =
+  | 'named_type' // Type references like "Pokemon", "ID"
+  | 'field' // Field selections like "name", "abilities"
+
+/**
+ * Subset of node types that are non-interactive user-defined names
+ */
+export type NonInteractiveNodeParentType =
+  | 'operation_definition' // Operation names like "GetPokemon"
+  | 'fragment_definition' // Fragment names like "PokemonDetails"
+  | 'variable_definition' // Variable definitions (though the 'variable' node itself represents the usage)
+  | 'argument' // Argument names
+
+/**
+ * Node types that represent keywords in GraphQL
+ */
+export type KeywordNodeType = 'query' | 'mutation' | 'subscription' | 'fragment' | 'on'
+
+/**
+ * Node types that represent literal values
+ */
+export type LiteralNodeType =
+  | 'string_value'
+  | 'int_value'
+  | 'float_value'
+  | 'boolean_value'
+  | 'null_value'
+  | 'enum_value'
+
+/**
+ * Node types that represent punctuation
+ */
+export type PunctuationNodeType =
+  | '{'
+  | '}'
+  | '('
+  | ')'
+  | '['
+  | ']'
+  | ':'
+  | '='
+  | ','
+  | '!'
+  | '|'
+  | '&'
+  | '@'
+  | '...'
+  | '$'
+
+/**
+ * Helper function to check if a node type is a keyword
+ */
+export function isKeywordNodeType(type: string): type is KeywordNodeType {
+  return type === 'query' || type === 'mutation' || type === 'subscription' || type === 'fragment' || type === 'on'
+}
+
+/**
+ * Helper function to check if a node type is a literal
+ */
+export function isLiteralNodeType(type: string): type is LiteralNodeType {
+  return type === 'string_value' || type === 'int_value' || type === 'float_value'
+    || type === 'boolean_value' || type === 'null_value' || type === 'enum_value'
+}
+
+/**
+ * Helper function to check if a node type is punctuation
+ */
+export function isPunctuationNodeType(type: string): type is PunctuationNodeType {
+  return ['{', '}', '(', ')', '[', ']', ':', '=', ',', '!', '|', '&', '@', '...', '$'].includes(type)
+}