@zyrab/domo-ssg 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Zyrab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights  
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell  
+copies of the Software, and to permit persons to whom the Software is  
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in  
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR  
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,  
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE  
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER  
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,  
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN  
+THE SOFTWARE.

package/README

@@ -0,0 +1,92 @@
+# @zyrab/domo-ssg
+
+**Minimal static site generator (SSG) for Domo**  
+Write JavaScript templates using [@zyrab/domo](https://www.npmjs.com/package/@zyrab/domo), define routes and layouts, and generate static HTML files with optional event hydration.
+
+---
+
+## ✨ Features
+
+- 🧱 Declarative page structure with `Domo` and `DomoSVG`
+- 🗺️ Simple nested route tree (`routes.js`)
+- 🎨 Custom layout wrapper (`layout.js`)
+- ⚡ Virtual DOM-like output (no DOM dependency during build)
+- 🧠 Hydration-ready: automatic inline scripts for events
+- 🧹 Built-in cleanup and sitemap generation
+
+---
+
+## 📦 Installation
+
+```bash
+pnpm add -D @zyrab/domo-ssg
+```
+
+Note: Use in a pnpm monorepo if you're working with other Domo packages like @zyrab/domo or @zyrab/domo-router.
+
+## 🛠 Usage
+
+### 1. Scaffold basic structure
+
+```bash
+pnpm exec domo-ssg-init
+```
+
+This will create:
+
+```js
+domo.config.js;
+routes.js;
+layout.js;
+```
+
+### 2. Add a script to your root package.json
+
+```json
+{
+  "scripts": {
+    "build": "pnpm --filter @zyrab/domo-ssg exec node src/index.js"
+  }
+}
+```
+
+### 3. Run the generator
+
+```bash
+pnpm build
+```
+
+# 🧩 Project Structure
+
+| File             | Purpose                             |
+| ---------------- | ----------------------------------- |
+| `routes.js`      | Your route tree (nested supported)  |
+| `layout.js`      | Optional layout wrapper             |
+| `domo.config.js` | Customize output dir, base URL, etc |
+
+# 🧪 Example Route File
+
+```js
+import { Domo } from "@zyrab/domo";
+
+export const routes = {
+  "/": () => Domo("div").txt("Hello Home"),
+  "/about": () => Domo("div").txt("About Page"),
+};
+```
+
+# ⚙️ Configuration (domo.config.js)
+
+```js
+export default {
+  outDir: "./dist",
+  routesFile: "./routes.js",
+  layout: "./layout.js",
+  exclude: ["css", "js", "assets"],
+  baseUrl: "https://example.com",
+};
+```
+
+# 📜 License
+
+MIT — © Zyrab

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@zyrab/domo-ssg",
+  "version": "0.1.0",
+  "description": "A Static Site Generator (SSG) for Domo-based projects.",
+  "main": "src/index.js",
+  "type": "module",
+  "bin": {
+    "domo-ssg-init": "./scripts/init.js"
+  },
+  "keywords": [
+    "domo",
+    "ssg",
+    "static site generator",
+    "build tool",
+    "frontend"
+  ],
+  "author": "Zyrab",
+  "license": "MIT",
+  "dependencies": {
+    "@zyrab/domo": "^1.2.0",
+    "@zyrab/domo-router": "^0.1.0"
+  },
+  "devDependencies": {},
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src/"
+  ],
+  "scripts": {
+    "build": "node src/index.js",
+    "dev": "node src/index.js --watch",
+    "clean": "node -e \"require('fs').rmSync('dist', { recursive: true, force: true }); console.log('Cleaned dist folder');\""
+  }
+}

package/scripts/init.js

@@ -0,0 +1,17 @@
+import { cpSync, existsSync } from "fs";
+import { resolve, join } from "path";
+
+const targetDir = process.cwd();
+const templateDir = resolve(import.meta.dirname, "../templates");
+
+const filesToCopy = ["routes.js", "layout.js", "domo.config.js"];
+
+for (const file of filesToCopy) {
+  const dest = join(targetDir, file);
+  if (!existsSync(dest)) {
+    cpSync(join(templateDir, file), dest);
+    console.log(`✅ Created: ${file}`);
+  } else {
+    console.log(`⚠️  Skipped (already exists): ${file}`);
+  }
+}

package/src/config.js

@@ -0,0 +1,37 @@
+// src/config.js
+import path from "path";
+
+/**
+ * Loads and processes the SSG configuration.
+ * @param {string} configFilePath - Absolute path to the user's config file.
+ * @returns {Promise<object>} The resolved configuration object.
+ */
+export async function loadConfig(configFilePath) {
+  // Default configuration values
+  const defaultConfig = {
+    outDir: "./dist",
+    routesFile: "./routes.js", // Assuming a common name for routes
+    layout: "./layout.js", // Assuming a common name for layout
+    exclude: ["css", "js", "assets", "robots.txt", "admin"],
+    baseUrl: "http://localhost:3000", // Default base URL for sitemap
+  };
+
+  let userConfig = {};
+  try {
+    const importedConfig = await import(configFilePath);
+    userConfig = importedConfig.default || importedConfig;
+  } catch (error) {
+    console.warn(`⚠️  No custom config file found at ${configFilePath}. Using default settings.`);
+  }
+
+  // Merge user config with defaults
+  const mergedConfig = { ...defaultConfig, ...userConfig };
+
+  // Resolve paths relative to the current working directory of the build script
+  // This assumes the config file itself specifies paths relative to its own location
+  mergedConfig.outDir = path.resolve(process.cwd(), mergedConfig.outDir);
+  mergedConfig.routesFile = path.resolve(process.cwd(), mergedConfig.routesFile);
+  mergedConfig.layout = path.resolve(process.cwd(), mergedConfig.layout);
+
+  return mergedConfig;
+}

package/src/event-utils.js

@@ -0,0 +1,130 @@
+// src/event-utils.js
+
+import { writeFileSync, mkdirSync, existsSync } from "fs";
+import { join } from "path";
+
+export function generateScriptContent(events) {
+  return events
+    .map(({ id, event, handlers }) => {
+      const varSet = new Set();
+      const logicLines = [];
+      const closureFunctions = [];
+      let matchCounter = 0;
+
+      for (const { type, selector, handler } of handlers) {
+        const fnSource = handler.toString();
+        const { name, body } = destructureFunction(fnSource);
+        const vars = extractExposedVariables(body);
+        vars.forEach((v) => varSet.add(v));
+
+        if (type === "closest") {
+          const matchVar = `match${++matchCounter}`;
+          logicLines.push(`const ${matchVar} = e.target.closest("${selector}");`);
+
+          if (name) {
+            logicLines.push(`if (${matchVar}) ${name}(e, ${matchVar});`);
+            closureFunctions.push(fnSource);
+          } else {
+            const adjustedBody = body.replace(/\btarget\b/g, matchVar);
+            logicLines.push(`if (${matchVar}) {\n${indent(adjustedBody, 2)}\n}`);
+          }
+        } else if (type === "match") {
+          const matchExpr = `e.target.matches("${selector}")`;
+
+          if (name) {
+            logicLines.push(`if (${matchExpr}) ${name}(e, e.target);`);
+            closureFunctions.push(fnSource);
+          } else {
+            const adjustedBody = body.replace(/\btarget\b/g, "e.target");
+            logicLines.push(`if (${matchExpr}) {\n${indent(adjustedBody, 2)}\n}`);
+          }
+        } else if (type === "direct") {
+          logicLines.push(body);
+        }
+      }
+
+      const varsStr = [...varSet].join("\n");
+      const handlerBody = `function(e) {\n${indent(logicLines.join("\n"), 1)}\n}`;
+      const closures = closureFunctions.length ? `\n\n${closureFunctions.join("\n\n")}` : "";
+
+      return `${
+        varsStr ? varsStr + "\n\n" : ""
+      }document.getElementById("${id}").addEventListener("${event}", ${handlerBody});${closures}`;
+    })
+    .join("\n\n\n");
+}
+
+export function collectEvents(node, out = []) {
+  if (!node || typeof node !== "object") return out;
+  const el = node.element;
+  if (Array.isArray(el._events) && el._events.length > 0) {
+    out.push(...el._events);
+  }
+
+  if (Array.isArray(el._child)) {
+    for (const child of el._child) {
+      collectEvents(child, out);
+    }
+  }
+
+  return out;
+}
+
+export function writeJs(constent, outputDir, path) {
+  const events = collectEvents(constent);
+  if (events.length <= 0) return;
+  const jsDir = join(outputDir, "js");
+  if (!existsSync(jsDir)) mkdirSync(jsDir);
+
+  const fileName = path === "/" ? "index.js" : path.replace(/^\/|\/$/g, "").replace(/\//g, "-") + ".js";
+  const jsContent = generateScriptContent(events);
+  writeFileSync(join(jsDir, fileName), jsContent, "utf8");
+
+  return join("js", fileName);
+}
+
+function extractExposedVariables(source) {
+  const lines = source.split("\n");
+  const injected = [];
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+
+    if (trimmed === "") continue;
+
+    if (trimmed.startsWith("// @ssg-let")) {
+      const decl = trimmed.replace("// @ssg-let", "").replace(/;$/, "").trim();
+      injected.push(`let ${decl};`);
+    } else if (trimmed.startsWith("// @ssg-const")) {
+      const decl = trimmed.replace("// @ssg-const", "").replace(/;$/, "").trim();
+      injected.push(`const ${decl};`);
+    } else if (!trimmed.startsWith("//")) {
+      break; // stop at first non-comment code line
+    }
+  }
+
+  return injected;
+}
+
+function destructureFunction(fnSource) {
+  const funcMatch = fnSource.match(/^function\s*([a-zA-Z0-9_$]*)\s*\([^)]*\)\s*\{([\s\S]*)\}$/);
+  if (funcMatch) {
+    const [, name, body] = funcMatch;
+    return { name: name.trim(), body: body.trim() };
+  }
+
+  const arrowMatch = fnSource.match(/^\(?[a-zA-Z0-9_,\s]*\)?\s*=>\s*\{([\s\S]*)\}$/);
+  if (arrowMatch) {
+    return { name: "", body: arrowMatch[1].trim() };
+  }
+
+  return { name: "", body: "" };
+}
+
+function indent(str, level = 1) {
+  const pad = "  ".repeat(level);
+  return str
+    .split("\n")
+    .map((line) => pad + line)
+    .join("\n");
+}

package/src/file-utils.js

@@ -0,0 +1,50 @@
+// src/file-utils.js
+import fs from "fs";
+import path from "path";
+
+/**
+ * Ensures that the directory for a given file path exists.
+ * Creates directories recursively if they don't.
+ * @param {string} filePath - The full path to the file.
+ * @returns {void}
+ */
+export function ensureDir(filePath) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+}
+
+/**
+ * Writes HTML content to a file in the output directory.
+ * @param {string} outputDir - The base output directory.
+ * @param {string} routePath - The URL path of the route (e.g., "/about", "/").
+ * @param {string} html - The HTML content to write.
+ * @returns {void}
+ */
+export function writeHTML(outputDir, routePath, html) {
+  // Adjust output path for root (/) and 404 (*) routes
+  const fileName = routePath === "/*" ? "404" : routePath === "/" ? "" : routePath;
+  const outPath = path.join(outputDir, fileName, "index.html");
+  ensureDir(outPath);
+  fs.writeFileSync(outPath, html, "utf8");
+  console.log(`Generated: ${path.relative(outputDir, outPath)}`);
+}
+
+/**
+ * Cleans the output directory by removing all content except specified exclusions.
+ * @param {string} outputDir - The directory to clean.
+ * @param {string[]} exclude - An array of file/folder names to exclude from cleaning.
+ * @returns {void}
+ */
+export function cleanOutputDir(outputDir, exclude) {
+  if (fs.existsSync(outputDir)) {
+    const entries = fs.readdirSync(outputDir);
+    for (const entry of entries) {
+      if (exclude.includes(entry)) continue;
+      const entryPath = path.join(outputDir, entry);
+      fs.rmSync(entryPath, { recursive: true, force: true });
+    }
+    console.log(`Cleaned output directory: ${outputDir}`);
+  } else {
+    fs.mkdirSync(outputDir, { recursive: true });
+    console.log(`Created output directory: ${outputDir}`);
+  }
+}

package/src/index.js

@@ -0,0 +1,43 @@
+// src/index.js (formerly build.mjs)
+import { pathToFileURL } from "url";
+import path from "path";
+import { loadConfig } from "./config.js";
+import { cleanOutputDir } from "./file-utils.js";
+import { generateSitemap } from "./sitemap.js";
+import { buildRoutes } from "./route-traversal.js";
+
+// __filename and __dirname equivalents for ES Modules
+
+async function main() {
+  // Determine where the user's config file should be
+  // Assumes config is at the root of the project where the script is run
+  const userConfigPath = path.resolve(process.cwd(), "domo.config.js");
+
+  const config = await loadConfig(pathToFileURL(userConfigPath).href);
+
+  // Import layout and route tree using pathToFileURL and .href for dynamic imports
+  const { routes } = await import(pathToFileURL(config.routesFile).href);
+  const { renderLayout } = await import(pathToFileURL(config.layout).href);
+
+  console.log("🚀 Starting Domo SSG build...");
+  console.log(`Output directory: ${config.outDir}`);
+  console.log(`Routes file: ${config.routesFile}`);
+  console.log(`Layout file: ${config.layout}`);
+
+  // 1. Clean the output directory
+  cleanOutputDir(config.outDir, config.exclude);
+
+  // 2. Build all routes recursively
+  await buildRoutes(routes, "", {}, renderLayout, config.outDir);
+
+  // 3. Generate sitemap
+  generateSitemap(config.outDir, config.baseUrl, config.exclude);
+
+  console.log("✅ Domo SSG build complete!");
+}
+
+// Execute the build process
+main().catch((error) => {
+  console.error("❌ Domo SSG build failed:", error);
+  process.exit(1); // Exit with a non-zero code to indicate failure
+});

package/src/route-handler.js

@@ -0,0 +1,67 @@
+// src/route-handler.js
+import Router from "@zyrab/domo-router";
+import { writeHTML } from "./file-utils.js";
+import { writeJs } from "./event-utils.js";
+
+/**
+ * Helper to join URL path segments correctly.
+ * @param {...string} segments - Path segments to join.
+ * @returns {string} The normalized joined path.
+ */
+export function joinPaths(...segments) {
+  let pathStr = segments
+    .filter(Boolean)
+    .map((s) => String(s).replace(/(^\/+|\/+$)/g, ""))
+    .join("/");
+
+  return "/" + pathStr.replace(/\/+/g, "/");
+}
+
+/**
+ * Handles the rendering and writing of a single route's HTML file.
+ * @param {object} routeConfig - Configuration for the current route.
+ * @param {string} routeConfig.path - The full URL path for this route (e.g., "/about", "/blog/post-1").
+ * @param {object} routeConfig.props - Properties to pass to the component.
+ * @param {Function} routeConfig.component - The component function that returns an HTMLElement or string.
+ * @param {string} [routeConfig.script] - Optional script to include in the layout.
+ * @param {object} [routeConfig.meta={}] - Optional metadata for the page (title, description).
+ * @param {Function} renderLayout - The layout rendering function from the user's config.
+ * @param {string} outputDir - The base output directory for generated files.
+ * @returns {Promise<void>}
+ */
+
+export async function handleRoute({ path, props, component, script, meta = {} }, renderLayout, outputDir) {
+  try {
+    // Set router info for server-side context
+    Router.setInfo(path, props);
+
+    // Calculate base depth for relative paths in layout if needed
+    const baseDepth = path === "/" ? 0 : path.split("/").filter(Boolean).length;
+
+    // Render the component content
+    const content = await component(props);
+
+    // --- Write JS file ---
+    const eScript = writeJs(content, outputDir, path);
+    let allScript = [];
+    if (Array.isArray(script) && script.length > 0) {
+      allScript.push(...script);
+    }
+    if (eScript && typeof eScript === "string" && eScript.trim() !== "") {
+      allScript.push(eScript);
+    }
+
+    // Render the full HTML layout
+    const html = await renderLayout(content, {
+      title: meta.title || "",
+      description: meta.description || "",
+      script: allScript,
+      baseDepth,
+    });
+
+    // Write the generated HTML to a file
+    writeHTML(outputDir, path, html);
+  } catch (e) {
+    console.warn(`⚠️  Error rendering ${path}:\n${e.stack}`);
+  }
+}

package/src/route-traversal.js

@@ -0,0 +1,135 @@
+// src/route-traversal.js
+import { handleRoute, joinPaths } from "./route-handler.js";
+
+/**
+ * Recursively builds HTML files for all defined routes, including nested and dynamic routes.
+ * @param {object} routes - The route configuration object.
+ * @param {string} [parentPath=""] - The path accumulated from parent routes.
+ * @param {object} [props={}] - Accumulated properties from parent dynamic routes.
+ * @param {Function} renderLayout - The layout rendering function.
+ * @param {string} outputDir - The base output directory.
+ * @returns {Promise<void>}
+ */
+export async function buildRoutes(routes, parentPath = "", props = {}, renderLayout, outputDir) {
+  for (const routeKey in routes) {
+    const r = routes[routeKey];
+    // Skip '/' if it's a child of another path (handled by parent's segment)
+    if (parentPath !== "" && routeKey === "/") continue;
+
+    // Handle dynamic routes with getDinamicList
+    if (r.getDinamicList) {
+      try {
+        // Extract parameter name from dynamic segment (e.g., ":slug" -> "slug")
+        const paramKey = routeKey.split(":").filter(Boolean).pop();
+        // The last segment of the parent path is the slug for nested dynamic lists
+        const slugParam = parentPath.split("/").filter(Boolean).pop();
+
+        const list = await r.getDinamicList(slugParam);
+
+        if (!Array.isArray(list) || list.length === 0) {
+          console.warn(`⚠️  No items returned for dynamic route at ${joinPaths(parentPath, routeKey)}`);
+          continue;
+        }
+
+        for (const item of list) {
+          if (!item[paramKey]) {
+            console.warn(
+              `⚠️  Missing required parameter '${paramKey}' in item for dynamic route at ${joinPaths(
+                parentPath,
+                routeKey
+              )}`
+            );
+            continue;
+          }
+
+          const segment = item[paramKey]; // Use the actual value from the item for the URL segment
+          const meta = { title: item.title, description: item.description, ...item.meta }; // Merge item's meta with route's meta
+          const routePath = joinPaths(parentPath, segment); // Full path for this specific dynamic item
+          const childProps = { ...props, [paramKey]: segment, itemData: item }; // Pass item data as prop
+
+          if (r.component) {
+            await handleRoute(
+              {
+                path: routePath,
+                props: childProps,
+                script: r.script,
+                component: r.component,
+                meta,
+              },
+              renderLayout,
+              outputDir
+            );
+          } else if (r.children?.["/"]?.component) {
+            // If dynamic route has children with a default component
+            await handleRoute(
+              {
+                path: routePath,
+                props: childProps,
+                script: r.children["/"].script,
+                component: r.children["/"].component,
+                meta: r.children["/"].meta || meta, // Children's meta takes precedence
+              },
+              renderLayout,
+              outputDir
+            );
+            // Recursively build children of this dynamic item if they exist
+            if (r.children) {
+              await buildRoutes(r.children, routePath, childProps, renderLayout, outputDir);
+            }
+          } else {
+            console.warn(
+              `⚠️  Dynamic route at ${routePath} missing a 'component' or a default 'children["/"].component'.`
+            );
+          }
+        }
+      } catch (e) {
+        console.warn(`⚠️  Skipped dynamic route generation for ${joinPaths(parentPath, routeKey)}: ${e.message}`);
+      }
+      continue; // Move to the next route key after handling dynamic list
+    }
+
+    // Handle static routes with a component
+    if (r.component) {
+      const routePath = joinPaths(parentPath, routeKey);
+      await handleRoute(
+        {
+          path: routePath,
+          props,
+          script: r.script,
+          component: r.component,
+          meta: r.meta,
+        },
+        renderLayout,
+        outputDir
+      );
+      // Continue to children if they exist for this static route
+      if (r.children) {
+        await buildRoutes(r.children, routePath, { ...props }, renderLayout, outputDir);
+      }
+      continue;
+    }
+
+    // Handle routes with only children (e.g., a folder route with no direct component, but an index component)
+    if (r.children) {
+      const routePath = joinPaths(parentPath, routeKey);
+      // Render the default child component ('/') for this path if it exists
+      if (r.children["/"]?.component) {
+        await handleRoute(
+          {
+            path: routePath,
+            props,
+            script: r.children["/"].script,
+            component: r.children["/"].component,
+            meta: r.children["/"].meta,
+          },
+          renderLayout,
+          outputDir
+        );
+      } else {
+        console.warn(`⚠️  Route at ${routePath} has children but no default component ('/')`);
+      }
+      // Recursively build the children
+      await buildRoutes(r.children, routePath, { ...props }, renderLayout, outputDir);
+    }
+  }
+}

package/src/sitemap.js

@@ -0,0 +1,54 @@
+// src/sitemap.js
+import fs from "fs";
+import path from "path";
+
+/**
+ * Generates an XML sitemap based on the generated HTML files in the output directory.
+ * @param {string} outputDir - The directory containing the generated HTML files.
+ * @param {string} baseUrl - The base URL of the website (e.g., "https://example.com").
+ * @param {string[]} exclude - Array of file/folder names to exclude from the sitemap.
+ * @returns {void}
+ */
+export function generateSitemap(outputDir, baseUrl, exclude) {
+  const urls = [];
+
+  function walk(dirPath) {
+    const entries = fs.readdirSync(dirPath, { withFileTypes: true });
+
+    for (const entry of entries) {
+      if (exclude.includes(entry.name)) continue;
+
+      const fullPath = path.join(dirPath, entry.name);
+      if (entry.isDirectory()) {
+        const indexPath = path.join(fullPath, "index.html");
+        if (fs.existsSync(indexPath)) {
+          let relative = path.relative(outputDir, fullPath);
+          // Convert Windows backslashes to forward slashes for URLs
+          let urlPath = "/" + relative.replace(/\\/g, "/");
+          // Handle root path specifically for sitemap
+          if (urlPath === "//" || urlPath === "/.") {
+            urlPath = "/";
+          }
+          urls.push(`${baseUrl}${urlPath}`);
+        }
+        walk(fullPath);
+      }
+    }
+  }
+
+  walk(outputDir);
+
+  const xml = `<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+${urls
+  .map(
+    (url) => `  <url>
+    <loc>${url}</loc>
+  </url>`
+  )
+  .join("\n")}
+</urlset>`;
+
+  fs.writeFileSync(path.join(outputDir, "sitemap.xml"), xml, "utf8");
+  console.log(`Generated sitemap.xml at: ${path.join(outputDir, "sitemap.xml")}`);
+}