npm - @jxsuite/compiler - Versions diffs - 0.0.1 - Mend

@jxsuite/compiler 0.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (18) hide show

package/dist/compiler.js +165 -0
package/package.json +38 -0
package/src/cli.js +59 -0
package/src/compiler.js +148 -0
package/src/shared.js +690 -0
package/src/site/content-loader.js +452 -0
package/src/site/context-injection.js +152 -0
package/src/site/head-merger.js +161 -0
package/src/site/layout-resolver.js +182 -0
package/src/site/pages-discovery.js +272 -0
package/src/site/prototype-resolver.js +161 -0
package/src/site/site-build.js +600 -0
package/src/site/site-loader.js +85 -0
package/src/targets/compile-class.js +194 -0
package/src/targets/compile-client.js +806 -0
package/src/targets/compile-element.js +619 -0
package/src/targets/compile-server.js +57 -0
package/src/targets/compile-static.js +155 -0

package/src/site/head-merger.js ADDED Viewed

@@ -0,0 +1,161 @@
+/**
+ * Head-merger.js — $head merge pipeline
+ *
+ * Merges <head> element arrays from three levels:
+ *
+ * 1. Site.json.$head — global (e.g., favicon, global stylesheet)
+ * 2. Layout.$head — layout-level (e.g., shared nav scripts)
+ * 3. Page.$head — page-specific (e.g., per-page meta tags)
+ *
+ * Per site-architecture spec §8:
+ *
+ * - Later levels override earlier levels for the same element
+ * - Deduplication by tagName + key attribute (name, property, rel+href)
+ * - Charset and viewport are auto-injected if missing
+ */
+/**
+ * Merge $head arrays from site, layout, and page levels.
+ *
+ * @param {any[]} [siteHead] - Site.json $head entries
+ * @param {any[]} [layoutHead] - Layout $head entries (may be empty)
+ * @param {any[]} [pageHead] - Page $head entries (may be empty)
+ * @param {any} [context] - { title, lang, charset, url, pageUrl }
+ * @returns {any[]} Merged, deduplicated $head array
+ */
+export function mergeHead(siteHead = [], layoutHead = [], pageHead = [], context = {}) {
+  // Start with auto-injected defaults
+  const defaults = [
+    { tagName: "meta", attributes: { charset: context.charset ?? "utf-8" } },
+    {
+      tagName: "meta",
+      attributes: { name: "viewport", content: "width=device-width, initial-scale=1" },
+    },
+  ];
+  // Merge layers: site → layout → page (later wins)
+  /** @type {Map<string, any>} */
+  const merged = new Map();
+  for (const entry of [...defaults, ...siteHead, ...layoutHead, ...pageHead]) {
+    const key = headEntryKey(entry);
+    merged.set(key, entry);
+  }
+  // Insert <title> if present
+  const title = context.title ?? context.siteName ?? "Jx Site";
+  merged.set("title", { tagName: "title", children: [title] });
+  // Add canonical URL if provided
+  if (context.pageUrl && context.siteUrl) {
+    const canonical = new URL(context.pageUrl, context.siteUrl).href;
+    merged.set("link:canonical", {
+      tagName: "link",
+      attributes: { rel: "canonical", href: canonical },
+    });
+  }
+  return Array.from(merged.values());
+}
+/**
+ * Generate a deduplication key for a <head> element. Elements with the same key are considered
+ * duplicates; the last one wins.
+ *
+ * @param {any} entry
+ * @returns {string}
+ */
+function headEntryKey(entry) {
+  if (!entry || typeof entry !== "object") return String(entry);
+  const tag = entry.tagName ?? "unknown";
+  const attrs = entry.attributes ?? {};
+  // <title> — singleton
+  if (tag === "title") return "title";
+  // <meta charset> — singleton
+  if (attrs.charset) return "meta:charset";
+  // <meta name="...""> — keyed by name
+  if (tag === "meta" && attrs.name) return `meta:${attrs.name}`;
+  // <meta property="..."> — keyed by property (Open Graph)
+  if (tag === "meta" && attrs.property) return `meta:${attrs.property}`;
+  // <link rel="..." href="..."> — keyed by rel+href
+  if (tag === "link" && attrs.rel) {
+    return `link:${attrs.rel}:${attrs.href ?? ""}`;
+  }
+  // <script src="..."> — keyed by src
+  if (tag === "script" && attrs.src) return `script:${attrs.src}`;
+  // <style> — unique per content hash
+  if (tag === "style") {
+    const content = Array.isArray(entry.children) ? entry.children.join("") : "";
+    return `style:${simpleHash(content)}`;
+  }
+  // Fallback — use full JSON serialization
+  return `${tag}:${JSON.stringify(entry)}`;
+}
+/**
+ * Simple string hash for deduplication (not cryptographic).
+ *
+ * @param {string} str
+ * @returns {string}
+ */
+function simpleHash(str) {
+  let hash = 0;
+  for (let i = 0; i < str.length; i++) {
+    hash = ((hash << 5) - hash + str.charCodeAt(i)) | 0;
+  }
+  return hash.toString(36);
+}
+/**
+ * Render a merged $head array to HTML string for insertion into <head>.
+ *
+ * @param {any[]} headEntries - Merged head entries
+ * @returns {string} HTML string
+ */
+export function renderHead(headEntries) {
+  return headEntries.map((/** @type {any} */ e) => renderHeadEntry(e)).join("\n  ");
+}
+/**
+ * Render a single $head entry to an HTML string.
+ *
+ * @param {any} entry
+ * @returns {string}
+ */
+function renderHeadEntry(entry) {
+  if (typeof entry === "string") return entry;
+  if (!entry || typeof entry !== "object") return "";
+  const tag = entry.tagName;
+  const attrs = entry.attributes ?? {};
+  const attrStr = Object.entries(attrs)
+    .map(([k, v]) => (v === true ? k : `${k}="${escapeAttr(/** @type {any} */ (v))}"`))
+    .join(" ");
+  const open = attrStr ? `<${tag} ${attrStr}>` : `<${tag}>`;
+  // Void elements (no closing tag)
+  const VOID = new Set(["meta", "link", "base", "br", "hr", "img", "input"]);
+  if (VOID.has(tag)) return open;
+  // Elements with content
+  const content = Array.isArray(entry.children) ? entry.children.join("") : "";
+  return `${open}${content}</${tag}>`;
+}
+/**
+ * @param {any} val
+ * @returns {string}
+ */
+function escapeAttr(val) {
+  return String(val).replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;");
+}

package/src/site/layout-resolver.js ADDED Viewed

@@ -0,0 +1,182 @@
+/**
+ * Layout-resolver.js — Layout loading and slot distribution at compile time
+ *
+ * Resolves $layout references, loads layout JSON files, and distributes page content into layout
+ * <slot> elements. This is the compile-time equivalent of the runtime's distributeSlots()
+ * algorithm.
+ *
+ * Per site-architecture spec §5:
+ *
+ * - Layouts are JSON files in the layouts/ directory
+ * - Pages reference layouts via "$layout": "./layouts/base.json"
+ * - The page's children are distributed into the layout's <slot> elements
+ * - Named slots use attributes.slot on page children
+ */
+import { readFileSync, existsSync } from "node:fs";
+import { resolve } from "node:path";
+/**
+ * Resolve a page's layout, wrapping the page content in the layout structure.
+ *
+ * @param {any} pageDoc - The raw page JSON document
+ * @param {any} projectConfig - Site configuration (for defaults.layout)
+ * @param {string} projectRoot - Project root directory
+ * @returns {any} The merged document (layout wrapping page content)
+ */
+export function resolveLayout(pageDoc, projectConfig, projectRoot) {
+  // Determine which layout to use
+  const layoutRef = pageDoc.$layout ?? projectConfig.defaults?.layout ?? null;
+  if (!layoutRef) {
+    // No layout — return page as-is
+    return pageDoc;
+  }
+  // Load the layout file
+  const layoutPath = resolve(projectRoot, layoutRef);
+  if (!existsSync(layoutPath)) {
+    throw new Error(`Layout not found: ${layoutRef} (resolved to ${layoutPath})`);
+  }
+  /** @type {any} */
+  let layoutDoc;
+  try {
+    layoutDoc = JSON.parse(readFileSync(layoutPath, "utf8"));
+  } catch (e) {
+    const err = /** @type {any} */ (e);
+    throw new Error(`Invalid layout JSON at ${layoutPath}: ${err.message}`);
+  }
+  // Check for nested layouts (layout inheriting from another layout)
+  if (layoutDoc.$layout) {
+    layoutDoc = resolveLayout(layoutDoc, projectConfig, projectRoot);
+  }
+  // Distribute page children into layout slots
+  const pageChildren = pageDoc.children ?? [];
+  const merged = deepClone(layoutDoc);
+  distributeSlots(merged, pageChildren);
+  // Merge page-level properties onto the resolved document
+  // Page state extends layout state
+  if (pageDoc.state) {
+    merged.state = { ...merged.state, ...pageDoc.state };
+  }
+  // Page $media extends layout $media
+  if (pageDoc.$media) {
+    merged.$media = { ...merged.$media, ...pageDoc.$media };
+  }
+  // Page style extends layout style
+  if (pageDoc.style) {
+    merged.style = { ...merged.style, ...pageDoc.style };
+  }
+  // Page attributes extend layout attributes
+  if (pageDoc.attributes) {
+    merged.attributes = { ...merged.attributes, ...pageDoc.attributes };
+  }
+  // Preserve page-level metadata
+  if (pageDoc.$head) merged._pageHead = pageDoc.$head;
+  if (pageDoc.title) merged._pageTitle = pageDoc.title;
+  // Remove $layout from merged doc (already resolved)
+  delete merged.$layout;
+  return merged;
+}
+/**
+ * Distribute children into <slot> elements within a layout document tree. This is the compile-time
+ * equivalent of the runtime's distributeSlots().
+ *
+ * Algorithm:
+ *
+ * 1. Find all <slot> elements in the layout tree
+ * 2. For each child with attributes.slot, distribute to the matching named slot
+ * 3. Remaining children go into the default (unnamed) slot
+ * 4. Replace each <slot> element with its distributed children
+ *
+ * @param {any} node - Layout document tree (mutated in place)
+ * @param {any[]} children - Page children to distribute
+ */
+function distributeSlots(node, children) {
+  if (!node || typeof node !== "object") return;
+  if (!Array.isArray(node.children)) return;
+  // Collect named and default children
+  /** @type {Map<string, any[]>} */
+  const named = new Map(); // slot name → children[]
+  /** @type {any[]} */
+  const defaults = []; // children without a slot target
+  for (const child of children) {
+    if (child && typeof child === "object" && child.attributes?.slot) {
+      const slotName = child.attributes.slot;
+      if (!named.has(slotName)) named.set(slotName, []);
+      /** @type {any[]} */ (named.get(slotName)).push(child);
+    } else {
+      defaults.push(child);
+    }
+  }
+  // Walk the tree and replace <slot> elements
+  fillSlots(node, named, defaults);
+}
+/**
+ * Recursively walk the tree and replace <slot> elements with distributed content.
+ *
+ * @param {any} node
+ * @param {Map<string, any[]>} named
+ * @param {any[]} defaults
+ */
+function fillSlots(node, named, defaults) {
+  if (!node || typeof node !== "object") return;
+  if (!Array.isArray(node.children)) return;
+  /** @type {any[]} */
+  const newChildren = [];
+  for (const child of node.children) {
+    if (child && typeof child === "object" && child.tagName === "slot") {
+      const slotName = child.attributes?.name;
+      if (slotName && named.has(slotName)) {
+        // Named slot — replace with matching children
+        newChildren.push(.../** @type {any[]} */ (named.get(slotName)));
+        named.delete(slotName); // consumed
+      } else if (!slotName && defaults.length > 0) {
+        // Default slot — replace with unassigned children
+        newChildren.push(...defaults);
+        // Don't clear defaults — only one default slot should exist,
+        // but if there are multiple, the first one wins
+      } else {
+        // No matching content — keep slot's fallback children
+        if (child.children) {
+          newChildren.push(...child.children);
+        }
+      }
+    } else {
+      // Not a slot — recurse into it
+      fillSlots(child, named, defaults);
+      newChildren.push(child);
+    }
+  }
+  node.children = newChildren;
+}
+/**
+ * Deep clone a JSON-serializable object.
+ *
+ * @param {any} obj
+ * @returns {any}
+ */
+function deepClone(obj) {
+  return JSON.parse(JSON.stringify(obj));
+}

package/src/site/pages-discovery.js ADDED Viewed

@@ -0,0 +1,272 @@
+/**
+ * Pages-discovery.js — File-based route discovery
+ *
+ * Scans the pages/ directory and builds a route table mapping URL paths to their source JSON files,
+ * layouts, and metadata.
+ *
+ * Conventions (per site-architecture spec §4): pages/index.json → / pages/about.json → /about
+ * pages/about/index.json → /about pages/blog/[slug].json → /blog/:slug (dynamic)
+ * pages/docs/[...path].json → /docs/* (catch-all) pages/_component.json → NOT routed (underscore
+ * prefix)
+ */
+import { readdirSync, readFileSync } from "node:fs";
+import { resolve, relative, extname, join } from "node:path";
+/**
+ * @typedef {object} Route
+ * @property {string} urlPattern - URL pattern (e.g. "/blog/:slug")
+ * @property {string} sourcePath - Absolute path to the .json source file
+ * @property {string} relativePath - Path relative to pages/ dir
+ * @property {boolean} isDynamic - Whether route has parameters
+ * @property {boolean} isCatchAll - Whether route uses [...param] spread
+ * @property {string[]} params - Parameter names (e.g. ["slug"])
+ * @property {string | null} $layout - Layout override from page frontmatter, if any
+ * @property {Record<string, string>} [_pathParams] - Resolved path parameters
+ */
+/**
+ * Discover all routable pages in a pages/ directory.
+ *
+ * @param {string} pagesDir - Absolute path to the pages/ directory
+ * @returns {Route[]} Sorted route table (static routes first, then dynamic)
+ */
+export function discoverPages(pagesDir) {
+  /** @type {Route[]} */
+  const routes = [];
+  walkDir(pagesDir, pagesDir, routes);
+  // Sort: static routes first, then by specificity (more segments = more specific)
+  routes.sort((a, b) => {
+    if (a.isDynamic !== b.isDynamic) return a.isDynamic ? 1 : -1;
+    if (a.isCatchAll !== b.isCatchAll) return a.isCatchAll ? 1 : -1;
+    return a.urlPattern.localeCompare(b.urlPattern);
+  });
+  return routes;
+}
+/**
+ * Recursively walk the pages directory tree.
+ *
+ * @param {string} dir
+ * @param {string} pagesRoot
+ * @param {Route[]} routes
+ */
+function walkDir(dir, pagesRoot, routes) {
+  const entries = readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const fullPath = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      // Skip underscore-prefixed directories
+      if (entry.name.startsWith("_")) continue;
+      walkDir(fullPath, pagesRoot, routes);
+      continue;
+    }
+    // Only process .json files
+    if (extname(entry.name) !== ".json") continue;
+    // Skip underscore-prefixed files (local components, not routes)
+    if (entry.name.startsWith("_")) continue;
+    const relativePath = relative(pagesRoot, fullPath);
+    const route = fileToRoute(relativePath, fullPath);
+    if (route) routes.push(route);
+  }
+}
+/**
+ * Convert a file path relative to pages/ into a Route object.
+ *
+ * @param {string} relativePath - E.g. "blog/[slug].json"
+ * @param {string} absolutePath - Full filesystem path
+ * @returns {Route}
+ */
+function fileToRoute(relativePath, absolutePath) {
+  // Remove .json extension
+  let urlPath = relativePath.replace(/\.json$/, "");
+  // Normalize path separators
+  urlPath = urlPath.split("\\").join("/");
+  // index files map to their parent directory
+  if (urlPath.endsWith("/index")) {
+    urlPath = urlPath.slice(0, -6) || "/";
+  } else if (urlPath === "index") {
+    urlPath = "/";
+  }
+  // Ensure leading slash
+  if (!urlPath.startsWith("/")) urlPath = "/" + urlPath;
+  // Extract parameters from bracket syntax
+  /** @type {string[]} */
+  const params = [];
+  let isDynamic = false;
+  let isCatchAll = false;
+  // Convert [param] → :param and [...param] → *
+  const urlPattern = urlPath.replace(
+    /\[\.\.\.(\w+)\]|\[(\w+)\]/g,
+    (/** @type {string} */ match, /** @type {string} */ spread, /** @type {string} */ named) => {
+      if (spread) {
+        isCatchAll = true;
+        isDynamic = true;
+        params.push(spread);
+        return "*";
+      }
+      isDynamic = true;
+      params.push(named);
+      return `:${named}`;
+    },
+  );
+  // Peek at the page JSON to extract $layout if present
+  /** @type {string | null} */
+  let $layout = null;
+  try {
+    const raw = JSON.parse(readFileSync(absolutePath, "utf8"));
+    if (typeof raw.$layout === "string") {
+      $layout = raw.$layout;
+    }
+  } catch {
+    // Skip unreadable files — will error during compilation
+  }
+  return {
+    urlPattern,
+    sourcePath: absolutePath,
+    relativePath,
+    isDynamic,
+    isCatchAll,
+    params,
+    $layout,
+  };
+}
+/**
+ * Expand dynamic routes by resolving $paths from each dynamic page.
+ *
+ * Supports three $paths shapes (per spec §4.3): 1. Collection-based: { collection: "blog", param:
+ * "slug", field: "id" } 2. Explicit values: { values: ["en", "fr"], param: "lang" } 3. Data file
+ * ref: { "$ref": "./data/products.json", param: "id", field: "sku" } 4. Legacy array: [{ slug:
+ * "hello" }, { slug: "world" }]
+ *
+ * @param {Route[]} routes - Discovered route table
+ * @param {string} projectRoot - Project root for resolving $ref paths
+ * @param {Map<string, any[]>} [collections] - Loaded content collections (from content-loader)
+ * @returns {Promise<Route[]>} Expanded routes with concrete paths
+ */
+export async function expandDynamicRoutes(routes, projectRoot, collections = new Map()) {
+  /** @type {Route[]} */
+  const expanded = [];
+  for (const route of routes) {
+    if (!route.isDynamic) {
+      expanded.push(route);
+      continue;
+    }
+    // Read the page to look for $paths
+    /** @type {any} */
+    let raw;
+    try {
+      raw = JSON.parse(readFileSync(route.sourcePath, "utf8"));
+    } catch {
+      expanded.push(route);
+      continue;
+    }
+    if (!raw.$paths) {
+      console.warn(`Warning: dynamic route ${route.urlPattern} has no $paths — skipping`);
+      continue;
+    }
+    const pathEntries = resolvePathEntries(raw.$paths, projectRoot, collections);
+    for (const pathEntry of pathEntries) {
+      let concreteUrl = route.urlPattern;
+      for (const [param, value] of Object.entries(pathEntry)) {
+        concreteUrl = concreteUrl.replace(`:${param}`, /** @type {string} */ (value));
+        concreteUrl = concreteUrl.replace("*", /** @type {string} */ (value));
+      }
+      expanded.push({
+        ...route,
+        urlPattern: concreteUrl,
+        isDynamic: false,
+        isCatchAll: false,
+        params: [],
+        _pathParams: pathEntry,
+      });
+    }
+  }
+  return expanded;
+}
+/**
+ * Resolve $paths into an array of param objects.
+ *
+ * @param {any} $paths - The $paths declaration
+ * @param {string} projectRoot
+ * @param {Map<string, any[]>} collections
+ * @returns {Record<string, any>[]} Array of { paramName: value } objects
+ */
+function resolvePathEntries($paths, projectRoot, collections) {
+  // Legacy: array of param objects
+  if (Array.isArray($paths)) {
+    return $paths;
+  }
+  // Collection-based: { collection: "blog", param: "slug", field: "id" }
+  if ($paths.collection) {
+    const entries = collections.get($paths.collection);
+    if (!entries || entries.length === 0) {
+      console.warn(
+        `Warning: $paths references collection "${$paths.collection}" but it has no entries`,
+      );
+      return [];
+    }
+    const param = $paths.param ?? "slug";
+    const field = $paths.field ?? "id";
+    return entries.map((/** @type {any} */ entry) => ({
+      [param]: field === "id" ? entry.id : (entry.data[field] ?? entry.id),
+    }));
+  }
+  // Explicit values: { values: ["en", "fr"], param: "lang" }
+  if (Array.isArray($paths.values)) {
+    const param = $paths.param ?? "value";
+    return $paths.values.map((/** @type {any} */ v) => ({ [param]: v }));
+  }
+  // Data file ref: { "$ref": "./data/products.json", param: "id", field: "sku" }
+  if ($paths.$ref) {
+    const filePath = resolve(projectRoot, $paths.$ref);
+    /** @type {any} */
+    let data;
+    try {
+      data = JSON.parse(readFileSync(filePath, "utf8"));
+    } catch (e) {
+      const err = /** @type {any} */ (e);
+      console.warn(`Warning: $paths.$ref could not load "${$paths.$ref}": ${err.message}`);
+      return [];
+    }
+    if (!Array.isArray(data)) {
+      console.warn(`Warning: $paths.$ref "${$paths.$ref}" must be a JSON array`);
+      return [];
+    }
+    const param = $paths.param ?? "id";
+    const field = $paths.field ?? "id";
+    return data.map((/** @type {any} */ item) => ({
+      [param]: item[field] ?? item.id ?? String(item),
+    }));
+  }
+  console.warn(`Warning: unrecognized $paths shape — skipping`);
+  return [];
+}