html-component-engine 0.1.0

package/src/engine/compiler.js

@@ -0,0 +1,312 @@
+import fs from 'fs/promises';
+import path from 'path';
+import { pathToFileURL } from 'url';
+import { parseComponentTag, parseVariants, parseSelfClosingComponentTag } from './utils.js';
+
+/**
+ * Compile HTML by resolving all components
+ * @param {string} html - The HTML content to compile
+ * @param {string} root - The root directory (pages directory)
+ * @param {string} projectRoot - The project root directory
+ * @returns {Promise<string>} - Compiled HTML
+ */
+export async function compileHtml(html, root, projectRoot = null) {
+  const effectiveProjectRoot = projectRoot || path.dirname(root);
+  let result = html;
+
+  // First, process components with children: <Component name="...">children</Component>
+  result = await processComponentsWithChildren(result, root, effectiveProjectRoot);
+
+  // Then, process self-closing components: <Component src="..." />
+  result = await processSelfClosingComponents(result, root, effectiveProjectRoot);
+
+  return result;
+}
+
+/**
+ * Process components with children (slot-based)
+ * Matches: <Component name="ComponentName">...children...</Component>
+ */
+async function processComponentsWithChildren(html, root, projectRoot) {
+  // Regex to match <Component name="...">...</Component>
+  const componentRegex = /<Component\s+name="([^"]+)"([^>]*)>([\s\S]*?)<\/Component>/g;
+
+  let result = html;
+  let matches = [...html.matchAll(componentRegex)];
+
+  for (const match of matches) {
+    const fullTag = match[0];
+    const componentName = match[1];
+    const attrsStr = match[2];
+    const children = match[3].trim();
+
+    // Parse additional attributes
+    const attrs = parseAttributes(attrsStr);
+
+    // Load component
+    let componentContent = await loadComponent(componentName, root, projectRoot, attrs);
+
+    if (componentContent === null) {
+      console.error(`Component "${componentName}" not found`);
+      result = result.replace(fullTag, `<!-- Component "${componentName}" not found -->`);
+      continue;
+    }
+
+    // Replace {{ children }} placeholder with actual children content
+    componentContent = componentContent.replace(/\{\{\s*children\s*\}\}/g, children);
+
+    // Replace props with {{key}} placeholders
+    for (const [key, value] of Object.entries(attrs)) {
+      componentContent = componentContent.replace(new RegExp(`\\{\\{\\s*${key}\\s*\\}\\}`, 'g'), value);
+    }
+
+    // Recursively compile nested components
+    const compiledComponent = await compileHtml(componentContent, root, projectRoot);
+    result = result.replace(fullTag, compiledComponent);
+  }
+
+  return result;
+}
+
+/**
+ * Process self-closing components
+ * Matches: <Component src="..." />
+ */
+async function processSelfClosingComponents(html, root, projectRoot) {
+  const componentRegex = /<Component[^>]+\/>/g;
+
+  let result = html;
+  const matches = [...html.matchAll(componentRegex)];
+
+  for (const match of matches) {
+    const tag = match[0];
+    const attrs = parseSelfClosingComponentTag(tag);
+    if (!attrs || !attrs.src) continue;
+
+    const name = attrs.src;
+    let componentContent = await loadComponent(name, root, projectRoot, attrs);
+
+    if (componentContent === null) {
+      console.error(`Component "${name}" not found`);
+      result = result.replace(tag, `<!-- Component "${name}" not found -->`);
+      continue;
+    }
+
+    // Parse variants (only for HTML content)
+    const variants = parseVariants(componentContent);
+
+    // Replace props with {{key}} placeholders
+    for (const [key, value] of Object.entries(attrs)) {
+      if (key === 'variant' && variants[value]) {
+        componentContent = componentContent.replace(/\{\{\s*variantClasses\s*\}\}/g, variants[value]);
+      } else if (key !== 'src' && key !== 'variant') {
+        componentContent = componentContent.replace(new RegExp(`\\{\\{\\s*${key}\\s*\\}\\}`, 'g'), value);
+      }
+    }
+
+    // If no variant specified, replace {{variantClasses}} with empty
+    componentContent = componentContent.replace(/\{\{\s*variantClasses\s*\}\}/g, '');
+
+    // Recursively compile nested components
+    const compiledComponent = await compileHtml(componentContent, root, projectRoot);
+    result = result.replace(tag, compiledComponent);
+  }
+
+  return result;
+}
+
+/**
+ * Load a component by name
+ * @param {string} name - Component name (e.g., "Card" or "main/Button")
+ * @param {string} root - The pages root directory
+ * @param {string} projectRoot - The project root directory
+ * @param {object} attrs - Component attributes/props
+ * @returns {Promise<string|null>} - Component content or null if not found
+ */
+async function loadComponent(name, root, projectRoot, attrs = {}) {
+  // Normalize name for path construction (handle both / and \)
+  const normalizedName = name.replace(/\\/g, '/');
+
+  // root = srcRoot (e.g., example/src)
+  // projectRoot = project root (e.g., example)
+  // Components are in srcRoot/components
+  const possiblePaths = [
+    path.join(root, 'components', `${normalizedName}.html`),           // srcRoot/components/
+    path.join(projectRoot, 'src', 'components', `${normalizedName}.html`), // projectRoot/src/components/
+    path.join(projectRoot, 'components', `${normalizedName}.html`),    // projectRoot/components/
+  ];
+
+  for (const componentPath of possiblePaths) {
+    try {
+      await fs.access(componentPath); // Check if file exists first
+      const content = await fs.readFile(componentPath, 'utf8');
+      return content;
+    } catch {
+      // Try .js file at the same location
+      const jsPath = componentPath.replace('.html', '.js');
+      try {
+        const componentModule = await import(pathToFileURL(jsPath));
+        const componentExport = componentModule.default || componentModule;
+
+        if (typeof componentExport === 'function') {
+          const props = { ...attrs };
+          delete props.src;
+          delete props.name;
+          return componentExport(props);
+        } else {
+          return String(componentExport);
+        }
+      } catch {
+        continue;
+      }
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Parse attributes from an attribute string
+ * @param {string} attrsStr - Attribute string like ' class="foo" id="bar"'
+ * @returns {object} - Object with attribute key-value pairs
+ */
+function parseAttributes(attrsStr) {
+  const attrs = {};
+  const attrRegex = /(\w+)="([^"]*)"/g;
+  let attrMatch;
+  while ((attrMatch = attrRegex.exec(attrsStr)) !== null) {
+    attrs[attrMatch[1]] = attrMatch[2];
+  }
+  return attrs;
+}
+
+/**
+ * Inline CSS from <link> tags into <style> tags
+ * @param {string} html - The HTML content
+ * @param {string} root - The src root directory
+ * @param {string} projectRoot - The project root directory
+ * @returns {Promise<string>} - HTML with inlined CSS
+ */
+export async function inlineCss(html, root, projectRoot) {
+  const linkRegex = /<link[^>]+rel=["']stylesheet["'][^>]*>/gi;
+  const matches = [...html.matchAll(linkRegex)];
+
+  let result = html;
+
+  for (const match of matches) {
+    const linkTag = match[0];
+    const hrefMatch = linkTag.match(/href=["']([^"']+)["']/);
+
+    if (!hrefMatch) continue;
+
+    let href = hrefMatch[1];
+
+    // Skip external URLs
+    if (href.startsWith('http://') || href.startsWith('https://')) {
+      continue;
+    }
+
+    // Resolve the CSS file path - try multiple locations
+    let cssPath = null;
+    let cssContent = null;
+
+    // Possible paths to check
+    const pathsToTry = [];
+
+    if (href.startsWith('/')) {
+      const cleanHref = href.slice(1);
+      // /styles/styles.css -> src/assets/styles/styles.css (publicDir pattern)
+      pathsToTry.push(path.join(root, 'assets', cleanHref));
+      // /assets/styles/styles.css -> src/assets/styles/styles.css
+      pathsToTry.push(path.join(root, cleanHref));
+      // Try project root
+      pathsToTry.push(path.join(projectRoot, 'src', 'assets', cleanHref));
+    } else {
+      // Relative path
+      pathsToTry.push(path.join(root, href));
+    }
+
+    for (const tryPath of pathsToTry) {
+      if (await fileExists(tryPath)) {
+        cssPath = tryPath;
+        break;
+      }
+    }
+
+    if (cssPath) {
+      try {
+        cssContent = await fs.readFile(cssPath, 'utf8');
+        const styleTag = `<style>\n${cssContent}\n</style>`;
+        result = result.replace(linkTag, styleTag);
+      } catch (error) {
+        console.warn(`Could not inline CSS from ${href}: ${error.message}`);
+      }
+    } else {
+      console.warn(`Could not find CSS file for ${href}`);
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Inline JS from <script src="..."> tags into inline <script> tags
+ * @param {string} html - The HTML content
+ * @param {string} root - The pages root directory
+ * @param {string} projectRoot - The project root directory
+ * @returns {Promise<string>} - HTML with inlined JS
+ */
+export async function inlineJs(html, root, projectRoot) {
+  const scriptRegex = /<script[^>]+src=["']([^"']+)["'][^>]*><\/script>/gi;
+  const matches = [...html.matchAll(scriptRegex)];
+
+  let result = html;
+
+  for (const match of matches) {
+    const scriptTag = match[0];
+    let src = match[1];
+
+    // Skip external URLs and Vite client
+    if (src.startsWith('http://') || src.startsWith('https://') || src.includes('@vite')) {
+      continue;
+    }
+
+    // Resolve the JS file path
+    let jsPath;
+    if (src.startsWith('/')) {
+      jsPath = path.join(projectRoot, 'src', 'assets', src.slice(1));
+      if (!await fileExists(jsPath)) {
+        jsPath = path.join(root, 'assets', src.slice(1));
+      }
+      if (!await fileExists(jsPath)) {
+        jsPath = path.join(root, src.slice(1));
+      }
+    } else {
+      jsPath = path.join(root, src);
+    }
+
+    try {
+      const jsContent = await fs.readFile(jsPath, 'utf8');
+      const inlineScriptTag = `<script>\n${jsContent}\n</script>`;
+      result = result.replace(scriptTag, inlineScriptTag);
+    } catch (error) {
+      console.warn(`Could not inline JS from ${src}: ${error.message}`);
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Check if a file exists
+ * @param {string} filePath - Path to check
+ * @returns {Promise<boolean>}
+ */
+async function fileExists(filePath) {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/engine/utils.js

@@ -0,0 +1,74 @@
+// Utility functions for the HTML Component Engine
+
+/**
+ * Parse a self-closing Component tag to extract attributes
+ * @param {string} tag - The full component tag, e.g., <Component src="Button" text="Click" />
+ * @returns {object|null} - Object with attribute key-value pairs, or null if invalid
+ */
+export function parseSelfClosingComponentTag(tag) {
+  const regex = /<Component\s+([^>]+)\s*\/>/;
+  const match = tag.match(regex);
+  if (!match) return null;
+
+  const attrs = {};
+  // Support hyphenated attributes like data-test, aria-label
+  const attrRegex = /([\w-]+)="([^"]*)"/g;
+  let attrMatch;
+  while ((attrMatch = attrRegex.exec(match[1])) !== null) {
+    attrs[attrMatch[1]] = attrMatch[2];
+  }
+  return attrs;
+}
+
+/**
+ * Parse a Component tag to extract attributes (legacy alias)
+ * @param {string} tag - The full component tag
+ * @returns {object|null} - Object with attribute key-value pairs, or null if invalid
+ */
+export function parseComponentTag(tag) {
+  return parseSelfClosingComponentTag(tag);
+}
+
+/**
+ * Parse variants from component HTML
+ * Looks for <!-- variants: primary=class1 class2, secondary=class3 -->
+ * @param {string} html - The component HTML
+ * @returns {object} - Map of variant name to classes
+ */
+export function parseVariants(html) {
+  const variants = {};
+  // Match HTML comment with variants - use non-greedy match
+  const regex = /<!--\s*variants:\s*(.+?)\s*-->/;
+  const match = html.match(regex);
+  if (match) {
+    const variantsStr = match[1];
+    const variantPairs = variantsStr.split(',');
+    for (const pair of variantPairs) {
+      const [name, ...classParts] = pair.split('=');
+      const classes = classParts.join('='); // Handle = in class names (unlikely but safe)
+      if (name && classes) {
+        variants[name.trim()] = classes.trim();
+      }
+    }
+  }
+  return variants;
+}
+
+/**
+ * Clean unused placeholders from compiled HTML
+ * @param {string} html - The compiled HTML
+ * @returns {string} - Cleaned HTML
+ */
+export function cleanUnusedPlaceholders(html) {
+  // Remove any remaining {{ ... }} placeholders
+  return html.replace(/\{\{\s*\w+\s*\}\}/g, '');
+}
+
+/**
+ * Normalize path separators to forward slashes
+ * @param {string} p - Path to normalize
+ * @returns {string} - Normalized path
+ */
+export function normalizePath(p) {
+  return p.replace(/\\/g, '/');
+}

package/src/index.js

@@ -0,0 +1,279 @@
+import { compileHtml, inlineCss, inlineJs } from './engine/compiler.js';
+import { cleanUnusedPlaceholders, normalizePath } from './engine/utils.js';
+import path from 'path';
+import fs from 'fs/promises';
+
+/**
+ * HTML Component Engine - Vite Plugin
+ * A lightweight static site compiler with component support
+ * 
+ * @param {object} options - Plugin options
+ * @param {string} options.srcDir - Source directory relative to project root (default: 'src')
+ * @param {string} options.componentsDir - Components directory name inside srcDir (default: 'components')
+ * @param {string} options.assetsDir - Assets directory name inside srcDir (default: 'assets')
+ * @param {boolean} options.inlineStyles - Whether to inline CSS (default: true for build)
+ * @param {boolean} options.inlineScripts - Whether to inline JS (default: true for build)
+ */
+export default function htmlComponentEngine(options = {}) {
+  // Handle null/undefined options
+  const opts = options || {};
+  const {
+    srcDir = 'src',
+    componentsDir = 'components',
+    assetsDir = 'assets',
+    inlineStyles = true,
+    inlineScripts = true,
+  } = opts;
+
+  let projectRoot;
+  let srcRoot;
+  let componentsRoot;
+  let assetsRoot;
+  let resolvedConfig;
+
+  return {
+    name: 'html-component-engine',
+
+    configResolved(config) {
+      resolvedConfig = config;
+      // Use process.cwd() as the project root - this is where the vite command is run from
+      // config.root can be unreliable with linked packages
+      projectRoot = process.cwd();
+      srcRoot = path.resolve(projectRoot, srcDir);
+      componentsRoot = path.join(srcRoot, componentsDir);
+      assetsRoot = path.join(srcRoot, assetsDir);
+    },
+
+    configureServer(server) {
+      // Add middleware BEFORE internal middlewares to intercept HTML requests
+      server.middlewares.use(async (req, res, next) => {
+        // Skip non-HTML requests and special Vite paths
+        if (req.url.startsWith('/@') || req.url.startsWith('/__')) {
+          return next();
+        }
+
+        // Skip asset requests (let Vite handle them via publicDir)
+        if (req.url.match(/\.(css|js|png|jpg|jpeg|gif|svg|ico|woff|woff2|ttf|eot|json)$/i)) {
+          return next();
+        }
+
+        let url;
+        if (req.url === '/' || req.url === '/index' || req.url === '/index.html') {
+          url = 'index.html';
+        } else if (req.url.endsWith('.html')) {
+          url = req.url.slice(1);
+        } else {
+          // Check if req.url + '.html' exists
+          const potential = req.url.slice(1) + '.html';
+          const filePathCheck = path.join(srcRoot, potential);
+          try {
+            await fs.access(filePathCheck);
+            url = potential;
+          } catch {
+            return next();
+          }
+        }
+
+        const filePath = path.join(srcRoot, url);
+
+        try {
+          let html = await fs.readFile(filePath, 'utf8');
+
+          // Compile components
+          html = await compileHtml(html, srcRoot, projectRoot);
+
+          // Clean unused placeholders
+          html = cleanUnusedPlaceholders(html);
+
+          // Inject Vite HMR client script
+          if (html.includes('</body>')) {
+            html = html.replace('</body>', '<script type="module" src="/@vite/client"></script></body>');
+          } else {
+            html += '<script type="module" src="/@vite/client"></script>';
+          }
+
+          res.setHeader('Content-Type', 'text/html');
+          res.end(html);
+          return;
+        } catch (error) {
+          console.error(`[html-component-engine] Error processing ${filePath}:`, error.message);
+          next();
+        }
+      });
+    },
+
+    handleHotUpdate(ctx) {
+      const normalizedFile = normalizePath(ctx.file);
+      const normalizedSrcRoot = normalizePath(srcRoot);
+
+      // Reload on changes to src directory
+      if (normalizedFile.startsWith(normalizedSrcRoot)) {
+        console.log('Hot update for:', ctx.file, '- sending full-reload');
+        ctx.server.ws.send({ type: 'full-reload' });
+        return [];
+      }
+    },
+
+    /**
+     * Build hook - process all HTML files for production
+     */
+    async buildStart() {
+      if (resolvedConfig.command !== 'build') return;
+
+      console.log('\n🔨 HTML Component Engine - Build Started');
+      console.log(`   Source: ${srcRoot}`);
+      console.log(`   Components: ${componentsRoot}`);
+      console.log(`   Assets: ${assetsRoot}`);
+    },
+
+    /**
+     * Generate bundle - compile HTML and copy assets
+     */
+    async generateBundle(outputOptions, bundle) {
+      const outDir = outputOptions.dir || path.resolve(projectRoot, 'dist');
+
+      console.log(`\n📦 Generating output to: ${outDir}`);
+
+      // Get all HTML files from src directory (excluding components)
+      const htmlFiles = await getHtmlFiles(srcRoot, '', componentsDir);
+
+      console.log(`   Found ${htmlFiles.length} HTML file(s)`);
+
+      for (const htmlFile of htmlFiles) {
+        const filePath = path.join(srcRoot, htmlFile);
+        let html = await fs.readFile(filePath, 'utf8');
+
+        // Compile components
+        html = await compileHtml(html, srcRoot, projectRoot);
+
+        // Inline CSS if enabled
+        if (inlineStyles) {
+          html = await inlineCss(html, srcRoot, projectRoot);
+        }
+
+        // Inline JS if enabled
+        if (inlineScripts) {
+          html = await inlineJs(html, srcRoot, projectRoot);
+        }
+
+        // Clean unused placeholders
+        html = cleanUnusedPlaceholders(html);
+
+        // Remove Vite-specific scripts
+        html = html.replace(/<script[^>]*@vite[^>]*>[\s\S]*?<\/script>/gi, '');
+
+        // Add to bundle
+        const outputFileName = htmlFile;
+        this.emitFile({
+          type: 'asset',
+          fileName: outputFileName,
+          source: html,
+        });
+
+        console.log(`   ✓ Compiled: ${htmlFile}`);
+      }
+
+      // Copy ALL assets to dist/assets (including CSS for reference)
+      await copyAllAssets(assetsRoot, this);
+    },
+
+    /**
+     * Close bundle - cleanup and final processing
+     */
+    async closeBundle() {
+      if (resolvedConfig.command !== 'build') return;
+
+      console.log('\n✅ HTML Component Engine - Build Complete\n');
+    },
+  };
+}
+
+/**
+ * Get all HTML files recursively from a directory
+ * @param {string} dir - Directory to search
+ * @param {string} base - Base directory for relative paths
+ * @param {string} componentsDir - Components directory name to skip
+ * @returns {Promise<string[]>} - Array of relative file paths
+ */
+async function getHtmlFiles(dir, base = '', componentsDir = 'components') {
+  const files = [];
+
+  try {
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+
+    for (const entry of entries) {
+      const relativePath = base ? path.join(base, entry.name) : entry.name;
+
+      if (entry.isDirectory()) {
+        // Skip only the components directory
+        if (entry.name !== componentsDir) {
+          const subFiles = await getHtmlFiles(path.join(dir, entry.name), relativePath, componentsDir);
+          files.push(...subFiles);
+        }
+      } else if (entry.name.endsWith('.html')) {
+        files.push(relativePath);
+      }
+    }
+  } catch (error) {
+    console.warn(`Could not read directory ${dir}: ${error.message}`);
+  }
+
+  return files;
+}
+
+/**
+ * Copy ALL assets to output directory (including CSS/JS)
+ * @param {string} assetsPath - Assets directory path
+ * @param {object} context - Rollup plugin context
+ */
+async function copyAllAssets(assetsPath, context) {
+  try {
+    await fs.access(assetsPath);
+  } catch {
+    console.log('   No assets directory found, skipping asset copy');
+    return;
+  }
+
+  const assetFiles = await getAllFiles(assetsPath);
+
+  console.log(`   Copying ${assetFiles.length} asset file(s)`);
+
+  for (const file of assetFiles) {
+    const relativePath = path.relative(assetsPath, file);
+    const content = await fs.readFile(file);
+
+    context.emitFile({
+      type: 'asset',
+      fileName: path.join('assets', relativePath).replace(/\\/g, '/'),
+      source: content,
+    });
+  }
+}
+
+/**
+ * Get all files recursively from a directory
+ * @param {string} dir - Directory to search
+ * @returns {Promise<string[]>} - Array of absolute file paths
+ */
+async function getAllFiles(dir) {
+  const files = [];
+
+  try {
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+
+    for (const entry of entries) {
+      const fullPath = path.join(dir, entry.name);
+
+      if (entry.isDirectory()) {
+        const subFiles = await getAllFiles(fullPath);
+        files.push(...subFiles);
+      } else {
+        files.push(fullPath);
+      }
+    }
+  } catch (error) {
+    console.warn(`Could not read directory ${dir}: ${error.message}`);
+  }
+
+  return files;
+}