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

package/build/template/server/view.js

@@ -1,6 +1,6 @@
 import { createStaticHandler } from 'react-router';
 import PROJECT_DATA from 'virtual:polen/project/data.jsonsuper';
-import { routes } from '../routes.jsx';
+import { routes } from "../routes.js";
 export const view = createStaticHandler(routes, {
     basename: PROJECT_DATA.basePath === `/` ? undefined : PROJECT_DATA.basePath.slice(0, -1), // Remove trailing slash for React Router
 });

package/build/template/server/view.js.map

@@ -1 +1 @@
-{"version":3,"file":"view.js","sourceRoot":"","sources":["../../../src/template/server/view.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAA;AAClD,OAAO,YAAY,MAAM,sCAAsC,CAAA;AAC/D,OAAO,EAAE,MAAM,EAAE,MAAM,eAAe,CAAA;AAEtC,MAAM,CAAC,MAAM,IAAI,GAAG,mBAAmB,CAAC,MAAM,EAAE;IAC9C,QAAQ,EAAE,YAAY,CAAC,QAAQ,KAAK,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,YAAY,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,yCAAyC;CACpI,CAAC,CAAA"}
+{"version":3,"file":"view.js","sourceRoot":"","sources":["../../../src/template/server/view.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAA;AAClD,OAAO,YAAY,MAAM,sCAAsC,CAAA;AAC/D,OAAO,EAAE,MAAM,EAAE,MAAM,cAAe,CAAA;AAEtC,MAAM,CAAC,MAAM,IAAI,GAAG,mBAAmB,CAAC,MAAM,EAAE;IAC9C,QAAQ,EAAE,YAAY,CAAC,QAAQ,KAAK,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,YAAY,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,yCAAyC;CACpI,CAAC,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "polen",
-  "version": "0.10.0-next.10",
+  "version": "0.10.0-next.12",
   "type": "module",
   "description": "A framework for delightful GraphQL developer portals",
   "author": {
@@ -36,13 +36,58 @@
       "source": "./src/*.ts",
       "default": "./build/*.js"
     },
-    "#lib/mask": "./src/lib/mask/$.ts",
-    "#lib/mask/mask": "./src/lib/mask/$$.ts",
-    "#lib/task": "./src/lib/task/$.ts",
-    "#lib/task/task": "./src/lib/task/$$.ts",
-    "#lib/deployment": "./src/lib/deployment/$.ts",
-    "#lib/deployment/deployment": "./src/lib/deployment/$$.ts",
-    "#template/components/content/$$": "./src/template/components/content/$$.ts"
+    "#lib/mask": {
+      "source": "./src/lib/mask/$.ts",
+      "default": "./build/lib/mask/$.js"
+    },
+    "#lib/mask/mask": {
+      "source": "./src/lib/mask/$$.ts",
+      "default": "./build/lib/mask/$$.js"
+    },
+    "#lib/task": {
+      "source": "./src/lib/task/$.ts",
+      "default": "./build/lib/task/$.js"
+    },
+    "#lib/task/task": {
+      "source": "./src/lib/task/$$.ts",
+      "default": "./build/lib/task/$$.js"
+    },
+    "#lib/deployment": {
+      "source": "./src/lib/deployment/$.ts",
+      "default": "./build/lib/deployment/$.js"
+    },
+    "#lib/deployment/deployment": {
+      "source": "./src/lib/deployment/$$.ts",
+      "default": "./build/lib/deployment/$$.js"
+    },
+    "#lib/graphql-document": {
+      "source": "./src/lib/graphql-document/$.ts",
+      "default": "./build/lib/graphql-document/$.js"
+    },
+    "#lib/graphql-document/graphql-document": {
+      "source": "./src/lib/graphql-document/$$.ts",
+      "default": "./build/lib/graphql-document/$$.js"
+    },
+    "#lib/graphql-document/components/index": {
+      "source": "./src/lib/graphql-document/components/index.ts",
+      "default": "./build/lib/graphql-document/components/index.js"
+    },
+    "#lib/graphql-document/components/GraphQLDocumentWithSchema": {
+      "source": "./src/lib/graphql-document/components/GraphQLDocumentWithSchema.tsx",
+      "default": "./build/lib/graphql-document/components/GraphQLDocumentWithSchema.js"
+    },
+    "#lib/graphql-document/components/GraphQLDocument": {
+      "source": "./src/lib/graphql-document/components/GraphQLDocument.tsx",
+      "default": "./build/lib/graphql-document/components/GraphQLDocument.js"
+    },
+    "#lib/graphql-document/schema-context": {
+      "source": "./src/lib/graphql-document/schema-context.tsx",
+      "default": "./build/lib/graphql-document/schema-context.js"
+    },
+    "#template/components/content/$$": {
+      "source": "./src/template/components/content/$$.ts",
+      "default": "./build/template/components/content/$$.js"
+    }
   },
   "exports": {
     ".": {
@@ -51,6 +96,7 @@
     },
     "./components": {
       "source": "./src/exports/components.ts",
+      "import": "./build/exports/components.js",
       "default": "./build/exports/components.js"
     },
     "./polen": {
@@ -156,6 +202,7 @@
     "@tsconfig/node-lts": "^22.0.1",
     "@tsconfig/node22": "^22.0.2",
     "@tsconfig/strictest": "^2.0.5",
+    "@types/jsdom": "^21.1.7",
     "@types/node": "^24.0.3",
     "@types/react": "^19.1.8",
     "@types/react-dom": "^19.1.6",
@@ -175,6 +222,7 @@
     "fs-jetpack": "^5.1.0",
     "get-port-please": "^3.1.2",
     "globals": "^16.2.0",
+    "jsdom": "^26.1.0",
     "playwright": "1.53.0",
     "publint": "^0.3.12",
     "semver": "^7.7.2",

package/src/api/vite/plugins/core.ts

@@ -16,8 +16,6 @@ import { createLogger } from '../logger.ts'
 import { polenVirtual } from '../vi.ts'
 import { Pages } from './pages.ts'
 
-const debug = debugPolen.sub(`vite-plugin-core`)
-
 const viTemplateVariables = polenVirtual([`template`, `variables`])
 const viTemplateSchemaAugmentations = polenVirtual([`template`, `schema-augmentations`])
 const viProjectData = polenVirtual([`project`, `data.jsonsuper`], { allowPluginProcessing: true })
@@ -183,7 +181,6 @@ export const Core = (config: Config.Config): Vite.PluginOption[] => {
         {
           identifier: viProjectData,
           async loader() {
-            debug(`loadingViProjectDataVirtualModule`)
             const schema = await readSchema()
 
             // ━ Schema presence causes adding some navbar items

package/src/api/vite/plugins/pages.ts

@@ -110,7 +110,7 @@ export const Pages = ({
                 light: `github-light`,
                 dark: `tokyo-night`,
               },
-              defaultColor: false,
+              defaultColor: 'light',
               cssVariablePrefix: `--shiki-`,
               transformers: [
                 // Line numbers will be handled via CSS

package/src/exports/components.ts

@@ -1 +1,4 @@
-export * from '#template/components/content/$$'
+export { Callout, Tabs } from '@radix-ui/themes'
+export { GraphQLDocumentWithSchema } from '../template/components/content/GraphQLDocumentWrapper.tsx'
+export { mdxComponents } from '../template/components/MDXComponents.tsx'
+export { TestComponent } from '../template/components/TestComponent.tsx'

package/src/lib/graphql-document/$$.ts

@@ -0,0 +1,4 @@
+export * from './analysis.ts'
+export * from './positioning-simple.ts'
+export * from './schema-integration.ts'
+export * from './types.ts'

package/src/lib/graphql-document/$.test.ts

@@ -0,0 +1,132 @@
+import { describe, expect, it } from 'vitest'
+import { GraphQLDocument } from './$.ts'
+
+describe('GraphQLDocument', () => {
+  describe('analyze', () => {
+    it('should parse a simple query and extract identifiers', () => {
+      const source = `
+        query GetUser($id: ID!) {
+          user(id: $id) {
+            name
+            email
+          }
+        }
+      `
+
+      const result = GraphQLDocument.analyze(source)
+
+      expect(result.isValid).toBe(true)
+      expect(result.identifiers.all.length).toBeGreaterThan(0)
+
+      // Should find variable
+      const variables = result.identifiers.byKind.get('Variable') || []
+      expect(variables).toHaveLength(1)
+      expect(variables[0]?.name).toBe('id')
+
+      // Should find fields
+      const fields = result.identifiers.byKind.get('Field') || []
+      expect(fields.length).toBeGreaterThan(0)
+      const fieldNames = fields.map(f => f.name)
+      expect(fieldNames).toContain('user')
+      expect(fieldNames).toContain('name')
+      expect(fieldNames).toContain('email')
+
+      // Should find types
+      const types = result.identifiers.byKind.get('Type') || []
+      expect(types.length).toBeGreaterThan(0)
+      const typeNames = types.map(t => t.name)
+      expect(typeNames).toContain('ID')
+    })
+
+    it('should handle parsing errors gracefully', () => {
+      const invalidSource = `
+        query {
+          user(id: $id {
+            name
+          }
+        }
+      `
+
+      const result = GraphQLDocument.analyze(invalidSource)
+
+      expect(result.isValid).toBe(false)
+      expect(result.identifiers.errors.length).toBeGreaterThan(0)
+    })
+
+    it('should extract context information', () => {
+      const source = `
+        query GetUserPosts($userId: ID!) {
+          user(id: $userId) {
+            posts {
+              title
+              content
+            }
+          }
+        }
+      `
+
+      const result = GraphQLDocument.analyze(source)
+
+      const fields = result.identifiers.byKind.get('Field') || []
+      const userField = fields.find(f => f.name === 'user')
+
+      expect(userField?.context.operationType).toBe('query')
+      expect(userField?.context.operationName).toBe('GetUserPosts')
+      expect(userField?.context.selectionPath).toEqual(['user'])
+    })
+
+    it('should track parent types in nested selections', () => {
+      const source = `
+        query {
+          user {
+            posts {
+              title
+            }
+          }
+        }
+      `
+
+      const result = GraphQLDocument.analyze(source)
+
+      const fields = result.identifiers.byKind.get('Field') || []
+      const titleField = fields.find(f => f.name === 'title')
+
+      expect(titleField?.schemaPath).toEqual(['Post', 'title'])
+    })
+  })
+
+  describe('extractIdentifiers', () => {
+    it('should extract identifiers with positions', () => {
+      const source = `query { user { name } }`
+
+      const identifiers = GraphQLDocument.extractIdentifiers(source)
+
+      expect(identifiers.all.length).toBeGreaterThan(0)
+
+      // Each identifier should have position information
+      for (const identifier of identifiers.all) {
+        expect(identifier.position.start).toBeTypeOf('number')
+        expect(identifier.position.end).toBeTypeOf('number')
+        expect(identifier.position.line).toBeGreaterThan(0)
+        expect(identifier.position.column).toBeGreaterThan(0)
+      }
+    })
+
+    it('should create proper index maps', () => {
+      const source = `query { user { name } }`
+
+      const identifiers = GraphQLDocument.extractIdentifiers(source)
+
+      // Should have position index
+      expect(identifiers.byPosition.size).toBeGreaterThan(0)
+
+      // Should have kind index
+      expect(identifiers.byKind.size).toBeGreaterThan(0)
+
+      // All identifiers should be indexed
+      for (const identifier of identifiers.all) {
+        expect(identifiers.byPosition.get(identifier.position.start)).toBe(identifier)
+      }
+    })
+  })
+})

package/src/lib/graphql-document/$.ts

@@ -0,0 +1 @@
+export * as GraphQLDocument from './graphql-document.ts'

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

@@ -0,0 +1,102 @@
+# GraphQL Document Component
+
+Transform static GraphQL code blocks into interactive documentation with hyperlinks, tooltips, and schema validation.
+
+## Overview
+
+The GraphQL Document component enhances markdown code blocks with:
+
+- **Hyperlinked identifiers** - Click to navigate to reference documentation
+- **Hover tooltips** - View type information and descriptions
+- **Schema validation** - Highlight errors and deprecations
+- **Build-time checking** - Catch GraphQL errors during build
+
+## Architecture
+
+The implementation follows a layered architecture:
+
+1. **Analysis Layer** - Parses GraphQL and extracts identifiers
+2. **Schema Integration** - Resolves identifiers against GraphQL schema
+3. **Positioning Engine** - Maps source positions to DOM coordinates
+4. **UI Components** - React components for interactivity
+5. **Orchestration** - Main component tying everything together
+6. **Polen Integration** - Virtual modules and Vite plugin
+
+## Usage
+
+### Basic Setup
+
+1. Import the component in your MDX files:
+
+```typescript
+import { GraphQLDocumentWithSchema } from 'polen/components'
+```
+
+2. Use the component with GraphQL documents:
+
+```mdx
+<GraphQLDocumentWithSchema>
+{`query GetUser($id: ID!) {
+  user(id: $id) {
+    name
+    email
+  }
+}`}
+</GraphQLDocumentWithSchema>
+```
+
+### Component Props
+
+The `GraphQLDocumentWithSchema` component automatically loads the schema from Polen's virtual modules. You can pass options:
+
+```mdx
+<GraphQLDocumentWithSchema 
+  options={{ 
+    debug: true,
+    onNavigate: (url) => console.log('Navigate to:', url)
+  }}
+>
+{`query { user { name } }`}
+</GraphQLDocumentWithSchema>
+```
+
+### React Component
+
+Use the component directly in React:
+
+```tsx
+import { GraphQLDocument } from 'polen/lib/graphql-document'
+
+<GraphQLDocument schema={schema} options={{ debug: true }}>
+  {`query { user { name } }`}
+</GraphQLDocument>
+```
+
+## Implementation Details
+
+### Key Components
+
+- `GraphQLDocument` - Main React component
+- `IdentifierLink` - Interactive overlay for identifiers
+- `HoverTooltip` - Tooltip showing type information
+- `GraphQLDocumentWithSchema` - Wrapper that loads schema from Polen
+- `PolenSchemaResolver` - Schema integration
+
+### Testing
+
+Run tests with:
+
+```bash
+pnpm test:unit src/lib/graphql-document
+```
+
+### Type Safety
+
+Full TypeScript support with strict typing throughout.
+
+## Future Enhancements
+
+- Code folding for large queries
+- Inline query execution
+- Schema diff visualization
+- Export to various formats