Add HTML data grid, update docs and CLI, improve GraphQL UX

hotlong · hotlong · commit 9fe9c745ebf5 · 2026-01-16T04:39:42.000+08:00
Introduces a new agrid.html file with a web component for ObjectQL data grids. Updates documentation to reference Scalar API docs instead of Swagger, clarifies OpenAPI endpoints, and improves CLI serve/dev commands to output type generation paths and serve Scalar docs at the root. Adds Apollo Sandbox as the default GraphQL playground. Adjusts .gitignore to exclude generated types. Refines package.json scripts for clarity and disables example modules in config.
diff --git a/.gitignore b/.gitignore
@@ -15,4 +15,6 @@ docs/.vitepress/dist
 *.db
 
 # Example tutorials CHANGELOG (auto-generated, not tracked)
-examples/tutorials/*/CHANGELOG.md
+examples/tutorials/*/CHANGELOG.md
+# Generated Types
+generated/
diff --git a/docs/api/index.md b/docs/api/index.md
@@ -86,5 +86,5 @@ curl -X POST http://localhost:3000/api/objectql \
 ### Auto-Generated Specs
 
 For automated tool ingestion, use the following endpoints:
-- **OpenAPI / Swagger**: `/api/docs/swagger.json`
+- **OpenAPI / Swagger**: `/openapi.json` (Used by `/docs` UI)
 - **GraphQL Schema**: `/api/graphql/schema`
diff --git a/docs/guide/server-integration.md b/docs/guide/server-integration.md
@@ -73,18 +73,19 @@ interface ObjectQLRequest {
 }
 ```
 
-## 📖 OpenAPI / Swagger Support
+## 📖 OpenAPI Support
 
 `@objectql/server` automatically generates an OpenAPI 3.0 specification from your registered schema.
+This powers the built-in **API Docs** (available at `/docs` in CLI mode).
 
-You can access the spec by appending `/openapi.json` to your handler's mount path.
+You can access the raw spec by appending `/openapi.json` to your handler's mount path.
 
 **Example URLs:**
 *   **CLI Serve:** `http://localhost:3000/openapi.json`
 *   **Express (mounted at /api/objectql):** `http://localhost:3000/api/objectql/openapi.json`
 *   **Next.js (pages/api/objectql.ts):** `http://localhost:3000/api/objectql/openapi.json`
 
-This JSON file describes your data objects as "Virtual REST" endpoints (`GET /user`, `POST /user`, etc.), allowing you to easily import them into **Swagger UI**, **Postman**, or other API tools for visualization and testing.
+This JSON file describes your data objects as "Virtual REST" endpoints (`GET /user`, `POST /user`, etc.), allowing you to easily import them into **Scalar**, **Swagger UI**, **Postman**, or other API tools for visualization and testing.
 
 ## Example Usage
 
diff --git a/package.json b/package.json
@@ -2,18 +2,18 @@
   "name": "objectql-monorepo",
   "private": true,
   "scripts": {
-    "dev": "tsc -b -w",
+    "dev": "pnpm example:tracker",
     "build": "tsc -b && pnpm -r run build",
     "clean": "rm -rf dist packages/*/dist packages/*/node_modules node_modules",
     "test": "pnpm run check-versions && pnpm -r run test",
     "lint": "eslint packages --ext .ts,.tsx",
     "format": "prettier --write \"packages/**/*.{ts,tsx,json,md}\"",
     
-    "objectql": "node packages/tools/cli/dist/index.js",
     "cli:dev": "ts-node packages/tools/cli/src/index.ts",
     
-    "example:tracker": "pnpm objectql dev -d examples/showcase/project-tracker/src",
-    "example:erp": "pnpm objectql dev -d examples/showcase/enterprise-erp/src",
+    "objectql": "pnpm objectql",
+    "objectql:tracker": "pnpm objectql dev -d examples/showcase/project-tracker/src",
+    "objectql:erp": "pnpm objectql dev -d examples/showcase/enterprise-erp/src",
     
     "check-versions": "node scripts/check-versions.js",
     "docs:dev": "vitepress dev docs",
diff --git a/packages/runtime/server/src/adapters/graphql.ts b/packages/runtime/server/src/adapters/graphql.ts
@@ -4,6 +4,22 @@ import { ErrorCode } from '../types';
 import { IncomingMessage, ServerResponse } from 'http';
 import { graphql, GraphQLSchema, GraphQLObjectType, GraphQLString, GraphQLInt, GraphQLFloat, GraphQLBoolean, GraphQLList, GraphQLNonNull, GraphQLInputObjectType, GraphQLFieldConfigMap, GraphQLOutputType, GraphQLInputType } from 'graphql';
 
+const APOLLO_SANDBOX_HTML = `
+<!DOCTYPE html>
+<html lang="en">
+<body style="margin: 0; overflow-x: hidden; overflow-y: hidden">
+<div id="sandbox" style="height:100vh; width:100vw;"></div>
+<script src="https://embeddable-sandbox.cdn.apollographql.com/_latest/embeddable-sandbox.umd.production.min.js"></script>
+<script>
+ new window.EmbeddedSandbox({
+   target: "#sandbox",
+   initialEndpoint: window.location.href,
+   includeCookies: false, // Set to true if you need auth cookies
+ });
+</script>
+</body>
+</html>`;
+
 /**
  * Normalize ObjectQL response to use 'id' instead of '_id'
  */
@@ -421,6 +437,18 @@ export function createGraphQLHandler(app: IObjectQL) {
                 return;
             }
 
+            // HTML Playground Support (Apollo Sandbox)
+            // If it's a browser GET request without query params, show the playground
+            const acceptHeader = req.headers.accept || '';
+            const urlObj = new URL(req.url || '', `http://${req.headers.host || 'localhost'}`);
+            const hasQueryParams = urlObj.searchParams.has('query');
+
+            if (req.method === 'GET' && acceptHeader.includes('text/html') && !hasQueryParams) {
+                res.writeHead(200, { 'Content-Type': 'text/html' });
+                res.end(APOLLO_SANDBOX_HTML);
+                return;
+            }
+
             const url = req.url || '';
             const method = req.method || 'POST';
 
diff --git a/packages/tools/cli/README.md b/packages/tools/cli/README.md
@@ -449,7 +449,7 @@ objectql dev --no-watch
 ```
 
 The development server provides:
-- **Swagger UI**: `http://localhost:<port>/swagger` - Interactive API documentation
+- **API Docs (Scalar)**: `http://localhost:<port>/docs` - Interactive API documentation
 - **API Endpoint**: `http://localhost:<port>/` - Main API endpoint
 - **OpenAPI Spec**: `http://localhost:<port>/openapi.json` - Machine-readable API spec
 
@@ -602,7 +602,7 @@ objectql serve --dir ./src/schema --port 8080
 ```
 
 The server exposes:
-- **Web Console (Swagger UI)**: `http://localhost:<port>/swagger` (GET) - Interactive API explorer
+- **Web Console (API Docs)**: `http://localhost:<port>/docs` (GET) - Interactive API explorer
 - **JSON API Endpoint**: `http://localhost:<port>/` (POST)
 - **OpenAPI Spec**: `http://localhost:<port>/openapi.json` (GET)
 
diff --git a/packages/tools/cli/src/commands/dev.ts b/packages/tools/cli/src/commands/dev.ts
@@ -18,8 +18,8 @@ export async function dev(options: {
     console.log(chalk.cyan('🚀 Starting ObjectQL Development Server...'));
 
     const sourceDir = path.resolve(process.cwd(), options.dir || '.');
-    // Default output for types in dev mode
-    const typeOutputDir = path.resolve(process.cwd(), 'src/generated'); 
+    // Output types to the source directory under 'generated' folder
+    const typeOutputDir = path.join(sourceDir, 'generated'); 
 
     // 1. Initial Type Generation
     try {
@@ -35,6 +35,7 @@ export async function dev(options: {
     }
 
     console.log(chalk.blue(`\n🌐 Server context: ${sourceDir}`));
+    console.log(chalk.blue(`📁 Type output: ${typeOutputDir}`));
     
     // 3. Start Server
     await serve({ 
@@ -51,11 +52,15 @@ function startWatcher(sourceDir: string, outputDir: string) {
     console.log(chalk.yellow('👀 Watching for metadata changes...'));
     
     try {
-        // Recursive watch if supported (macOS/Windows support strict recursive)
-        // Linux might need fallback or libraries like chokidar, but we use fs.watch for zero-dep strictness
+        // Recursive watch 
         const watcher = fs.watch(sourceDir, { recursive: true }, (eventType, filename) => {
             if (!filename) return;
             
+            // Ignore generated directory to prevent loops if output is inside source
+            if (filename.includes('generated') || filename.includes('node_modules') || filename.includes('.git')) {
+                return;
+            }
+
             // Only care about YAML
             if (filename.endsWith('.yml') || filename.endsWith('.yaml')) {
                 // Debounce
@@ -69,14 +74,13 @@ function startWatcher(sourceDir: string, outputDir: string) {
                     } catch (e) {
                         console.error(chalk.red('Type generation failed:'), e);
                     }
-                }, 500); // 500ms debounce
+                }, 500); 
             }
         });
         
         watcher.on('error', (e) => console.error(chalk.red('Watcher error:'), e));
         
     } catch (e) {
         console.warn(chalk.yellow('Native recursive watch not supported or failed. Watching root only.'));
-        // Fallback logic could go here
     }
 }
diff --git a/packages/tools/cli/src/commands/serve.ts b/packages/tools/cli/src/commands/serve.ts
@@ -1,17 +1,17 @@
 import { ObjectQL } from '@objectql/core';
 import { SqlDriver } from '@objectql/driver-sql';
 import { ObjectLoader, loadModules } from '@objectql/platform-node';
-import { createNodeHandler } from '@objectql/server';
+import { createNodeHandler, createGraphQLHandler } from '@objectql/server';
 import { createServer } from 'http';
 import * as path from 'path';
 import * as fs from 'fs';
 import chalk from 'chalk';
 
-const CONSOLE_HTML = `
+const SCALAR_HTML = `
 <!DOCTYPE html>
 <html>
   <head>
-    <title>ObjectQL API Reference (Scalar)</title>
+    <title>ObjectQL API Reference</title>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
     <style>
@@ -122,20 +122,26 @@ export async function serve(options: {
 
     // 3. Create Handler
     const internalHandler = createNodeHandler(app);
+    const graphqlHandler = createGraphQLHandler(app);
 
     // 4. Start Server
     const server = createServer(async (req, res) => {
-        // Serve Swagger UI
-        if (req.method === 'GET' && (req.url === '/swagger' || req.url === '/swagger/')) {
+        // Serve API Docs at Root (Default)
+        if (req.method === 'GET' && (req.url === '/' || req.url === '/docs' || req.url === '/docs/')) {
             res.writeHead(200, { 'Content-Type': 'text/html' });
-            res.end(CONSOLE_HTML);
+            res.end(SCALAR_HTML);
             return;
         }
 
-        // Redirect / to /swagger for better DX
-        if (req.method === 'GET' && req.url === '/') {
-            res.writeHead(302, { 'Location': '/swagger' });
-            res.end();
+        // GraphQL Endpoint & Playground (Keep for compatibility)
+        if (req.url === '/graphql' || req.url === '/graphql/') {
+            await graphqlHandler(req, res);
+            return;
+        }
+
+        // Keep /api/graphql as alias for compatibility
+        if (req.url?.startsWith('/api/graphql')) {
+            await graphqlHandler(req, res);
             return;
         }
 
@@ -169,10 +175,10 @@ export async function serve(options: {
         server.listen(port, () => {
             server.removeListener('error', onError);
             console.log(chalk.green(`\n🚀 Server ready at http://localhost:${port}`));
-            console.log(chalk.green(`📚 Swagger UI:   http://localhost:${port}/swagger`));
-            console.log(chalk.blue(`📖 OpenAPI Spec:  http://localhost:${port}/openapi.json`));
+            console.log(chalk.blue(`📖 API Docs (Scalar):   http://localhost:${port}/`));
+            
             console.log(chalk.gray('\nTry a curl command:'));
-            console.log(`curl -X POST http://localhost:${port} -H "Content-Type: application/json" -d '{"op": "find", "object": "YourObject", "args": {}}'`);
+            console.log(`curl -X POST http://localhost:${port} -H "Content-Type: application/json" -d '{"op": "find", "object": "tasks", "args": {}}'`);
         });
     };
 
