@jqhtml/core 2.2.222

package/laravel-bridge/examples/node-integration.js

@@ -0,0 +1,201 @@
+#!/usr/bin/env node
+
+/**
+ * Example Node.js integration for sending JQHTML errors to Laravel
+ *
+ * This shows how to compile JQHTML templates and send any errors
+ * to a Laravel backend for proper error handling and display.
+ */
+
+import { Lexer, Parser, CodeGenerator, JQHTMLParseError } from '@jqhtml/parser';
+import fs from 'fs';
+import fetch from 'node-fetch'; // or axios, etc.
+
+/**
+ * Compile a JQHTML template and handle errors
+ */
+async function compileTemplate(templatePath, laravelEndpoint) {
+  try {
+    // Read template file
+    const source = fs.readFileSync(templatePath, 'utf8');
+    const filename = templatePath;
+
+    // Compile with source maps
+    const lexer = new Lexer(source);
+    const tokens = lexer.tokenize();
+    const parser = new Parser(tokens, source, filename);
+    const ast = parser.parse();
+
+    const generator = new CodeGenerator();
+    const result = generator.generateWithSourceMap(ast, filename, source);
+
+    // Success - return compiled code
+    return {
+      success: true,
+      code: result.code,
+      sourceMap: result.map
+    };
+
+  } catch (error) {
+    // Format error for Laravel
+    const errorData = formatErrorForLaravel(error, templatePath);
+
+    // Send to Laravel if endpoint provided
+    if (laravelEndpoint) {
+      await sendErrorToLaravel(errorData, laravelEndpoint);
+    }
+
+    // Return error response
+    return {
+      success: false,
+      error: errorData
+    };
+  }
+}
+
+/**
+ * Format a JavaScript error for Laravel consumption
+ */
+function formatErrorForLaravel(error, templatePath) {
+  // Check if it's a JQHTML parse error with full details
+  if (error instanceof JQHTMLParseError || error.name === 'JQHTMLParseError') {
+    return {
+      message: error.message,
+      filename: error.filename || templatePath,
+      line: error.line,
+      column: error.column,
+      source: error.source,
+      suggestion: error.suggestion,
+      severity: error.severity || 'error',
+      endLine: error.endLine,
+      endColumn: error.endColumn
+    };
+  }
+
+  // Generic error - try to extract what we can
+  const errorData = {
+    message: error.message || String(error),
+    filename: templatePath,
+    severity: 'error'
+  };
+
+  // Try to parse location from error message
+  const locationMatch = error.message.match(/at line (\d+), column (\d+)/);
+  if (locationMatch) {
+    errorData.line = parseInt(locationMatch[1]);
+    errorData.column = parseInt(locationMatch[2]);
+  }
+
+  return errorData;
+}
+
+/**
+ * Send error data to Laravel backend
+ */
+async function sendErrorToLaravel(errorData, endpoint) {
+  try {
+    const response = await fetch(endpoint, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Accept': 'application/json'
+      },
+      body: JSON.stringify({
+        error: errorData,
+        context: {
+          node_version: process.version,
+          timestamp: new Date().toISOString(),
+          environment: process.env.NODE_ENV || 'development'
+        }
+      })
+    });
+
+    if (!response.ok) {
+      console.error('Failed to send error to Laravel:', response.statusText);
+    }
+
+    return response.json();
+
+  } catch (err) {
+    console.error('Error communicating with Laravel:', err);
+  }
+}
+
+/**
+ * Express/HTTP endpoint for template compilation
+ *
+ * This could be used in a Node.js service that compiles templates
+ * for a Laravel application.
+ */
+export function createCompilationEndpoint(app, laravelErrorEndpoint) {
+  app.post('/compile-jqhtml', async (req, res) => {
+    const { template, filename, source } = req.body;
+
+    try {
+      // Compile template
+      const lexer = new Lexer(source || template);
+      const tokens = lexer.tokenize();
+      const parser = new Parser(tokens, source || template, filename);
+      const ast = parser.parse();
+
+      const generator = new CodeGenerator();
+      const result = generator.generateWithSourceMap(
+        ast,
+        filename || 'template.jqhtml',
+        source || template
+      );
+
+      // Success response
+      res.json({
+        success: true,
+        compiled: {
+          code: result.code,
+          map: result.map
+        }
+      });
+
+    } catch (error) {
+      // Format error for Laravel
+      const errorData = formatErrorForLaravel(error, filename);
+
+      // Send error to Laravel for logging/display
+      if (laravelErrorEndpoint) {
+        sendErrorToLaravel(errorData, laravelErrorEndpoint);
+      }
+
+      // Return error response
+      res.status(400).json({
+        success: false,
+        error: errorData
+      });
+    }
+  });
+}
+
+/**
+ * CLI usage example
+ */
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const templatePath = process.argv[2];
+  const laravelEndpoint = process.argv[3] || process.env.LARAVEL_ERROR_ENDPOINT;
+
+  if (!templatePath) {
+    console.error('Usage: node-integration.js <template-file> [laravel-endpoint]');
+    process.exit(1);
+  }
+
+  compileTemplate(templatePath, laravelEndpoint).then(result => {
+    if (result.success) {
+      console.log('Compilation successful!');
+      console.log('Code length:', result.code.length);
+      console.log('Source map:', result.sourceMap ? 'Generated' : 'Not generated');
+    } else {
+      console.error('Compilation failed!');
+      console.error(result.error);
+      process.exit(1);
+    }
+  });
+}
+
+// Export for use as module
+export { compileTemplate, formatErrorForLaravel, sendErrorToLaravel };

package/laravel-bridge/src/JqhtmlErrorFormatter.php

@@ -0,0 +1,187 @@
+<?php
+
+namespace Jqhtml\LaravelBridge;
+
+use Throwable;
+
+class JqhtmlErrorFormatter
+{
+    protected $sourceMapPath;
+    protected $showSourceContext;
+    protected $sourceMapCache = [];
+
+    public function __construct(?string $sourceMapPath = null, bool $showSourceContext = true)
+    {
+        $this->sourceMapPath = $sourceMapPath;
+        $this->showSourceContext = $showSourceContext;
+    }
+
+    /**
+     * Format a JQHTML exception for Laravel's error handler
+     */
+    public function format(JqhtmlException $exception): array
+    {
+        $data = [
+            'message' => $exception->getMessage(),
+            'exception' => get_class($exception),
+            'file' => $exception->getTemplateFile() ?? $exception->getFile(),
+            'line' => $exception->getTemplateLine() ?? $exception->getLine(),
+            'column' => $exception->getTemplateColumn(),
+            'error_type' => $exception->getErrorType(),
+        ];
+
+        if ($exception->getSuggestion()) {
+            $data['suggestion'] = $exception->getSuggestion();
+        }
+
+        if ($this->showSourceContext && $exception->getSourceCode()) {
+            $data['source_context'] = $this->getSourceContext($exception);
+        }
+
+        // Try to resolve source map if we have a compiled file location
+        if ($exception->getCompiledFile() && $this->sourceMapPath) {
+            $data['source_map'] = $this->resolveSourceMap($exception);
+        }
+
+        return $data;
+    }
+
+    /**
+     * Format for JSON responses
+     */
+    public function formatForJson(JqhtmlException $exception): array
+    {
+        return [
+            'error' => true,
+            'type' => 'jqhtml_error',
+            'message' => $exception->getMessage(),
+            'details' => $this->format($exception),
+        ];
+    }
+
+    /**
+     * Get source code context for display
+     */
+    protected function getSourceContext(JqhtmlException $exception): array
+    {
+        $source = $exception->getSourceCode();
+        $line = $exception->getTemplateLine();
+        $column = $exception->getTemplateColumn();
+
+        if (!$source || !$line) {
+            return [];
+        }
+
+        $lines = explode("\n", $source);
+        $lineIndex = $line - 1;
+
+        // Get 5 lines before and after for context
+        $contextSize = 5;
+        $start = max(0, $lineIndex - $contextSize);
+        $end = min(count($lines) - 1, $lineIndex + $contextSize);
+
+        $context = [];
+        for ($i = $start; $i <= $end; $i++) {
+            $context[] = [
+                'line_number' => $i + 1,
+                'content' => $lines[$i],
+                'is_error_line' => $i === $lineIndex,
+                'error_column' => $i === $lineIndex ? $column : null,
+            ];
+        }
+
+        return $context;
+    }
+
+    /**
+     * Attempt to resolve source map for better error location
+     */
+    protected function resolveSourceMap(JqhtmlException $exception): ?array
+    {
+        $compiledFile = $exception->getCompiledFile();
+        if (!$compiledFile || !file_exists($compiledFile)) {
+            return null;
+        }
+
+        // Look for source map file
+        $mapFile = $compiledFile . '.map';
+        if (!file_exists($mapFile)) {
+            // Try in the configured source map directory
+            if ($this->sourceMapPath) {
+                $mapFile = $this->sourceMapPath . '/' . basename($compiledFile) . '.map';
+                if (!file_exists($mapFile)) {
+                    return null;
+                }
+            } else {
+                return null;
+            }
+        }
+
+        // Load and parse source map
+        if (!isset($this->sourceMapCache[$mapFile])) {
+            $mapContent = file_get_contents($mapFile);
+            $this->sourceMapCache[$mapFile] = json_decode($mapContent, true);
+        }
+
+        $sourceMap = $this->sourceMapCache[$mapFile];
+        if (!$sourceMap) {
+            return null;
+        }
+
+        return [
+            'version' => $sourceMap['version'] ?? null,
+            'sources' => $sourceMap['sources'] ?? [],
+            'file' => $sourceMap['file'] ?? null,
+            'has_mappings' => !empty($sourceMap['mappings']),
+        ];
+    }
+
+    /**
+     * Convert a generic exception to JQHTML exception if it contains JQHTML error data
+     */
+    public function wrapException(Throwable $exception): Throwable
+    {
+        // Check if the exception message contains JQHTML error data
+        $message = $exception->getMessage();
+
+        // Look for JQHTML error patterns
+        if (strpos($message, 'JQHTMLParseError') !== false ||
+            strpos($message, 'at line') !== false && strpos($message, 'column') !== false) {
+
+            // Try to extract error details from the message
+            $templateFile = null;
+            $templateLine = null;
+            $templateColumn = null;
+
+            // Extract location info from "at filename:line:column" format
+            if (preg_match('/at\s+([^:]+):(\d+):(\d+)/', $message, $matches)) {
+                $templateFile = $matches[1];
+                $templateLine = (int)$matches[2];
+                $templateColumn = (int)$matches[3];
+            } elseif (preg_match('/at\s+line\s+(\d+),\s+column\s+(\d+)/', $message, $matches)) {
+                $templateLine = (int)$matches[1];
+                $templateColumn = (int)$matches[2];
+            }
+
+            // Extract suggestion if present
+            $suggestion = null;
+            if (preg_match('/Did you\s+(.+?)\?/', $message, $matches)) {
+                $suggestion = 'Did you ' . $matches[1] . '?';
+            }
+
+            return new JqhtmlException(
+                $message,
+                $templateFile,
+                $templateLine,
+                $templateColumn,
+                null,
+                $suggestion,
+                'parse',
+                $exception->getCode(),
+                $exception
+            );
+        }
+
+        return $exception;
+    }
+}

package/laravel-bridge/src/JqhtmlException.php

@@ -0,0 +1,173 @@
+<?php
+
+namespace Jqhtml\LaravelBridge;
+
+use Illuminate\View\ViewException;
+use Throwable;
+
+class JqhtmlException extends ViewException
+{
+    protected $templateFile;
+    protected $templateLine;
+    protected $templateColumn;
+    protected $sourceCode;
+    protected $suggestion;
+    protected $errorType;
+    protected $compiledFile;
+
+    public function __construct(
+        string $message,
+        ?string $templateFile = null,
+        ?int $templateLine = null,
+        ?int $templateColumn = null,
+        ?string $sourceCode = null,
+        ?string $suggestion = null,
+        string $errorType = 'parse',
+        int $code = 0,
+        ?Throwable $previous = null
+    ) {
+        // Call ViewException constructor with template file and line info
+        // ViewException signature: __construct($message, $code = 0, $severity = 1, $filename = '', $lineno = 0, $previous = null)
+        parent::__construct(
+            $message,
+            $code,
+            1, // severity
+            $templateFile ?? '',
+            $templateLine ?? 0,
+            $previous
+        );
+
+        $this->templateFile = $templateFile;
+        $this->templateLine = $templateLine;
+        $this->templateColumn = $templateColumn;
+        $this->sourceCode = $sourceCode;
+        $this->suggestion = $suggestion;
+        $this->errorType = $errorType;
+    }
+
+    /**
+     * Create from a JavaScript error object or JSON string
+     */
+    public static function createFromJsError($jsError, ?string $compiledFile = null): self
+    {
+        if (is_string($jsError)) {
+            $jsError = json_decode($jsError, true);
+        }
+
+        return new self(
+            $jsError['message'] ?? 'Unknown JQHTML error',
+            $jsError['filename'] ?? $jsError['templateFile'] ?? null,
+            $jsError['line'] ?? null,
+            $jsError['column'] ?? null,
+            $jsError['source'] ?? null,
+            $jsError['suggestion'] ?? null,
+            $jsError['severity'] ?? 'error'
+        );
+    }
+
+    public function getTemplateFile(): ?string
+    {
+        return $this->templateFile;
+    }
+
+    public function getTemplateLine(): ?int
+    {
+        return $this->templateLine;
+    }
+
+    public function getTemplateColumn(): ?int
+    {
+        return $this->templateColumn;
+    }
+
+    public function getSourceCode(): ?string
+    {
+        return $this->sourceCode;
+    }
+
+    public function getSuggestion(): ?string
+    {
+        return $this->suggestion;
+    }
+
+    public function getErrorType(): string
+    {
+        return $this->errorType;
+    }
+
+    public function getCompiledFile(): ?string
+    {
+        return $this->compiledFile;
+    }
+
+    public function setCompiledFile(string $file): self
+    {
+        $this->compiledFile = $file;
+        return $this;
+    }
+
+    /**
+     * Get formatted error message with context
+     */
+    public function getFormattedMessage(): string
+    {
+        $message = $this->getMessage();
+
+        if ($this->suggestion) {
+            $message .= "\n" . $this->suggestion;
+        }
+
+        if ($this->templateFile) {
+            $message .= sprintf(
+                "\n  at %s:%d:%d",
+                $this->templateFile,
+                $this->templateLine ?? 0,
+                $this->templateColumn ?? 0
+            );
+        }
+
+        if ($this->sourceCode && $this->templateLine) {
+            $message .= "\n\n" . $this->getCodeSnippet();
+        }
+
+        return $message;
+    }
+
+    /**
+     * Get code snippet with error highlighting
+     */
+    protected function getCodeSnippet(): string
+    {
+        if (!$this->sourceCode || !$this->templateLine) {
+            return '';
+        }
+
+        $lines = explode("\n", $this->sourceCode);
+        $lineIndex = $this->templateLine - 1;
+
+        // Show 3 lines before and after for context
+        $contextLines = 3;
+        $startLine = max(0, $lineIndex - $contextLines);
+        $endLine = min(count($lines) - 1, $lineIndex + $contextLines);
+
+        $snippet = '';
+        for ($i = $startLine; $i <= $endLine; $i++) {
+            $lineNum = $i + 1;
+            $isErrorLine = $i === $lineIndex;
+            $prefix = $isErrorLine ? '>' : ' ';
+
+            // Line number with padding
+            $lineNumStr = str_pad((string)$lineNum, 5, ' ', STR_PAD_LEFT);
+            $snippet .= sprintf("%s %s | %s\n", $prefix, $lineNumStr, $lines[$i]);
+
+            // Add pointer to error column
+            if ($isErrorLine && $this->templateColumn) {
+                $spaces = str_repeat(' ', $this->templateColumn + 8);
+                $carets = str_repeat('^', min(strlen($lines[$i]) - $this->templateColumn + 1, 20));
+                $snippet .= $spaces . $carets . "\n";
+            }
+        }
+
+        return $snippet;
+    }
+}

package/laravel-bridge/src/JqhtmlExceptionRenderer.php

@@ -0,0 +1,93 @@
+<?php
+
+namespace Jqhtml\LaravelBridge;
+
+use Illuminate\Contracts\View\View;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+use Illuminate\Http\Response;
+use Throwable;
+
+class JqhtmlExceptionRenderer
+{
+    protected $formatter;
+
+    public function __construct(JqhtmlErrorFormatter $formatter)
+    {
+        $this->formatter = $formatter;
+    }
+
+    /**
+     * Render a JQHTML exception for display
+     */
+    public function render(Request $request, JqhtmlException $exception): ?Response
+    {
+        if ($request->expectsJson()) {
+            return $this->renderJson($exception);
+        }
+
+        // For development, enhance the error page with JQHTML-specific info
+        if (app()->hasDebugModeEnabled()) {
+            return $this->renderDebugView($exception);
+        }
+
+        // In production, return null to let Laravel handle it normally
+        return null;
+    }
+
+    /**
+     * Render JSON error response
+     */
+    protected function renderJson(JqhtmlException $exception): JsonResponse
+    {
+        return response()->json(
+            $this->formatter->formatForJson($exception),
+            500
+        );
+    }
+
+    /**
+     * Render debug view with enhanced JQHTML error information
+     */
+    protected function renderDebugView(JqhtmlException $exception): ?Response
+    {
+        // Get formatted error data
+        $errorData = $this->formatter->format($exception);
+
+        // If using Laravel's Ignition error page, enhance it with our data
+        if (class_exists(\Spatie\LaravelIgnition\Facades\Flare::class)) {
+            \Spatie\LaravelIgnition\Facades\Flare::context('JQHTML Error', $errorData);
+            return null; // Let Ignition handle the rendering
+        }
+
+        // If using older Laravel or custom error handling
+        try {
+            // Check if we have a custom view
+            if (view()->exists('jqhtml::error')) {
+                return response()->view('jqhtml::error', [
+                    'exception' => $exception,
+                    'error_data' => $errorData,
+                ], 500);
+            }
+        } catch (Throwable $e) {
+            // Fall back to letting Laravel handle it
+        }
+
+        return null;
+    }
+
+    /**
+     * Check if an exception should be handled by this renderer
+     */
+    public function shouldHandle(Throwable $exception): bool
+    {
+        if ($exception instanceof JqhtmlException) {
+            return true;
+        }
+
+        // Check if it's a wrapped JQHTML error
+        $message = $exception->getMessage();
+        return strpos($message, 'JQHTMLParseError') !== false ||
+               strpos($message, 'JQHTML') !== false;
+    }
+}