@jxsuite/compiler 0.10.1 → 0.10.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/compiler",
-  "version": "0.10.1",
+  "version": "0.10.2",
   "description": "Jx static HTML compiler, island detector, and site builder",
   "license": "MIT",
   "repository": {
@@ -37,8 +37,8 @@
   },
   "dependencies": {
     "@apidevtools/json-schema-ref-parser": "^15.3.5",
-    "@jxsuite/parser": "^0.10.0",
-    "@jxsuite/runtime": "^0.10.0",
+    "@jxsuite/parser": "^0.10.1",
+    "@jxsuite/runtime": "^0.10.1",
     "remark-gfm": "^4.0.1",
     "remark-stringify": "^11.0.0",
     "sharp": "^0.34.5",

package/src/site/content-loader.js

@@ -1,8 +1,8 @@
 /**
- * Content-loader.js — Content collection loader
+ * Content-loader.js — Content type loader
  *
- * Loads content collections defined in project.json's `collections` key. Supports Markdown (.md),
- * JSON (.json), and CSV (.csv) source files.
+ * Loads content types defined in project.json's `contentTypes` key. Supports Markdown (.md), JSON
+ * (.json), and CSV (.csv) source files.
  *
  * Phase 2 implementation of site-architecture spec §6.
  *
@@ -99,7 +99,7 @@ let _mdModule = null;
 
 /**
  * Lazily import @jxsuite/parser for Markdown support. This avoids hard dependency — only loads when
- * MD collections exist.
+ * MD content types exist.
  *
  * @returns {Promise<any>}
  */
@@ -172,7 +172,7 @@ function loadJSONEntries(filePath) {
  * Load a CSV file into ContentEntry(s).
  *
  * @param {string} filePath - Absolute path to .csv file
- * @param {any} [schema] - Collection schema (for type coercion)
+ * @param {any} [schema] - Content type schema (for type coercion)
  * @returns {object[]} Array of ContentEntry shapes
  */
 function loadCSVEntries(filePath, schema) {
@@ -198,10 +198,10 @@ function loadCSVEntries(filePath, schema) {
 // ─── Content Config ───────────────────────────────────────────────────────────
 
 /**
- * Load and parse content collections config from project.json.
+ * Load and parse content types config from project.json.
  *
  * @param {string} projectRoot - Project root directory
- * @param {Record<string, any>} [projectConfig] - Already-loaded project config with `collections`
+ * @param {Record<string, any>} [projectConfig] - Already-loaded project config with `contentTypes`
  *   key
  * @returns {{ config: any; contentDir: string } | null} Parsed config or null if no content dir
  */
@@ -209,68 +209,68 @@ export function loadContentConfig(projectRoot, projectConfig = undefined) {
   const contentDir = resolve(projectRoot, "content");
 
   /** @type {any} */
-  const config = { collections: projectConfig?.collections ?? {} };
+  const config = { contentTypes: projectConfig?.contentTypes ?? {} };
 
   return { config, contentDir };
 }
 
-// ─── Collection Loading ───────────────────────────────────────────────────────
+// ─── Content Type Loading ────────────────────────────────────────────────────
 
 /**
- * Load all content collections defined in project.json.
+ * Load all content types defined in project.json.
  *
  * @param {string} projectRoot - Project root directory
  * @param {Record<string, any>} [projectConfig] - Already-loaded project config
- * @returns {Promise<Map<string, any[]>>} Map of collection name → array of ContentEntry
+ * @returns {Promise<Map<string, any[]>>} Map of content type name → array of ContentEntry
  */
-export async function loadCollections(projectRoot, projectConfig = undefined) {
+export async function loadContentTypes(projectRoot, projectConfig = undefined) {
   const result = loadContentConfig(projectRoot, projectConfig);
   if (!result) return new Map();
 
   const { config } = result;
   /** @type {Map<string, any[]>} */
-  const collections = new Map();
+  const contentTypes = new Map();
 
-  for (const [name, collectionDef] of Object.entries(config.collections)) {
-    const entries = await loadCollection(name, /** @type {any} */ (collectionDef), projectRoot);
-    collections.set(name, entries);
+  for (const [name, contentTypeDef] of Object.entries(config.contentTypes)) {
+    const entries = await loadContentType(name, /** @type {any} */ (contentTypeDef), projectRoot);
+    contentTypes.set(name, entries);
   }
 
-  return collections;
+  return contentTypes;
 }
 
 /**
- * Get the $elements array for a specific collection, if defined in project.json collections.
+ * Get the $elements array for a specific content type, if defined in project.json contentTypes.
  *
  * @param {string} projectRoot - Project root directory
- * @param {string} collectionName - Name of the collection
+ * @param {string} contentTypeName - Name of the content type
  * @param {Record<string, any>} [projectConfig] - Already-loaded project config
  * @returns {any[] | undefined}
  */
-export function getCollectionElements(projectRoot, collectionName, projectConfig = undefined) {
+export function getContentTypeElements(projectRoot, contentTypeName, projectConfig = undefined) {
   const result = loadContentConfig(projectRoot, projectConfig);
   if (!result) return undefined;
-  const def = result.config.collections?.[collectionName];
+  const def = result.config.contentTypes?.[contentTypeName];
   return def?.$elements;
 }
 
 /**
- * Load a single collection by its definition.
+ * Load a single content type by its definition.
  *
- * @param {string} name - Collection name
- * @param {any} collectionDef - Collection definition from project.json
+ * @param {string} name - Content type name
+ * @param {any} contentTypeDef - Content type definition from project.json
  * @param {string} projectRoot - Absolute path to project root directory
  * @returns {Promise<any[]>} Array of ContentEntry
  */
-async function loadCollection(name, collectionDef, projectRoot) {
-  const source = collectionDef.source;
-  const schema = collectionDef.schema;
+async function loadContentType(name, contentTypeDef, projectRoot) {
+  const source = contentTypeDef.source;
+  const schema = contentTypeDef.schema;
 
-  // Derive directive allowedNames from collection $elements (tag names from npm packages)
+  // Derive directive allowedNames from content type $elements (tag names from npm packages)
   /** @type {any} */
-  const directiveOptions = collectionDef.$elements?.length
+  const directiveOptions = contentTypeDef.$elements?.length
     ? {
-        allowedNames: collectionDef.$elements
+        allowedNames: contentTypeDef.$elements
           .filter((/** @type {any} */ e) => typeof e === "string" || e?.$ref)
           .map((/** @type {any} */ e) => (typeof e === "string" ? e : e.$ref)),
       }
@@ -306,14 +306,14 @@ async function loadCollection(name, collectionDef, projectRoot) {
 // ─── Schema Validation ────────────────────────────────────────────────────────
 
 /**
- * Validate content entries against their collection schema. Logs warnings for missing required
+ * Validate content entries against their content type schema. Logs warnings for missing required
  * fields and type mismatches.
  *
  * @param {any[]} entries - Array of ContentEntry
- * @param {any} schema - JSON Schema for the collection
- * @param {string} collectionName - For error messages
+ * @param {any} schema - JSON Schema for the content type
+ * @param {string} contentTypeName - For error messages
  */
-function validateEntries(entries, schema, collectionName) {
+function validateEntries(entries, schema, contentTypeName) {
   const required = schema.required ?? [];
   const properties = schema.properties ?? {};
 
@@ -322,7 +322,7 @@ function validateEntries(entries, schema, collectionName) {
     for (const field of required) {
       if (!(field in entry.data) || entry.data[field] == null) {
         console.warn(
-          `Content validation: "${collectionName}/${entry.id}" missing required field "${field}"`,
+          `Content validation: "${contentTypeName}/${entry.id}" missing required field "${field}"`,
         );
       }
     }
@@ -335,36 +335,36 @@ function validateEntries(entries, schema, collectionName) {
 
       if (d.type === "string" && typeof value !== "string") {
         console.warn(
-          `Content validation: "${collectionName}/${entry.id}" field "${field}" expected string, got ${typeof value}`,
+          `Content validation: "${contentTypeName}/${entry.id}" field "${field}" expected string, got ${typeof value}`,
         );
       } else if (d.type === "number" && typeof value !== "number") {
         console.warn(
-          `Content validation: "${collectionName}/${entry.id}" field "${field}" expected number, got ${typeof value}`,
+          `Content validation: "${contentTypeName}/${entry.id}" field "${field}" expected number, got ${typeof value}`,
         );
       } else if (d.type === "boolean" && typeof value !== "boolean") {
         console.warn(
-          `Content validation: "${collectionName}/${entry.id}" field "${field}" expected boolean, got ${typeof value}`,
+          `Content validation: "${contentTypeName}/${entry.id}" field "${field}" expected boolean, got ${typeof value}`,
         );
       } else if (d.type === "array" && !Array.isArray(value)) {
         console.warn(
-          `Content validation: "${collectionName}/${entry.id}" field "${field}" expected array, got ${typeof value}`,
+          `Content validation: "${contentTypeName}/${entry.id}" field "${field}" expected array, got ${typeof value}`,
         );
       }
     }
   }
 }
 
-// ─── Collection Querying ──────────────────────────────────────────────────────
+// ─── Content Type Querying ───────────────────────────────────────────────────
 
 /**
- * Query a loaded collection with filter, sort, and limit. Implements the ContentCollection
+ * Query a loaded content type with filter, sort, and limit. Implements the ContentCollection
  * $prototype resolution.
  *
- * @param {any[]} entries - Full collection entries
+ * @param {any[]} entries - Full content type entries
  * @param {any} [query] - Query options
  * @returns {any[]} Filtered, sorted, limited entries
  */
-export function queryCollection(entries, query = {}) {
+export function queryContentType(entries, query = {}) {
   let result = [...entries];
 
   // Filter
@@ -401,9 +401,9 @@ export function queryCollection(entries, query = {}) {
 }
 
 /**
- * Find a single entry by ID in a collection. Implements the ContentEntry $prototype resolution.
+ * Find a single entry by ID in a content type. Implements the ContentEntry $prototype resolution.
  *
- * @param {any[]} entries - Full collection entries
+ * @param {any[]} entries - Full content type entries
  * @param {string} id - Entry ID to find
  * @returns {any | null} The matching entry or null
  */
@@ -411,30 +411,30 @@ export function findEntry(entries, id) {
   return entries.find((/** @type {any} */ e) => e.id === id) ?? null;
 }
 
-// ─── Collection Reference Resolution ─────────────────────────────────────────
+// ─── Content Type Reference Resolution ──────────────────────────────────────
 
 /**
- * Resolve cross-collection $ref references in entry data. For example, a blog post's `author:
- * "jane-doe"` with a schema `$ref` to the authors collection gets resolved to the full author
+ * Resolve cross-content-type $ref references in entry data. For example, a blog post's `author:
+ * "jane-doe"` with a schema `$ref` to the authors content type gets resolved to the full author
  * entry.
  *
- * @param {Map<string, any[]>} collections - All loaded collections @param {any} config -
+ * @param {Map<string, any[]>} contentTypes - All loaded content types @param {any} config -
  * Content.config.json
  */
-export function resolveCollectionRefs(collections, config) {
-  for (const [name, collectionDef] of Object.entries(config.collections)) {
-    const cd = /** @type {any} */ (collectionDef);
+export function resolveContentTypeRefs(contentTypes, config) {
+  for (const [name, contentTypeDef] of Object.entries(config.contentTypes)) {
+    const cd = /** @type {any} */ (contentTypeDef);
     const schema = cd.schema;
     if (!schema?.properties) continue;
 
-    const entries = collections.get(name);
+    const entries = contentTypes.get(name);
     if (!entries) continue;
 
     for (const [field, def] of Object.entries(schema.properties)) {
       const d = /** @type {any} */ (def);
-      if (!d.$ref?.startsWith("#/collections/")) continue;
-      const refCollection = d.$ref.replace("#/collections/", "");
-      const refEntries = collections.get(refCollection);
+      if (!d.$ref?.startsWith("#/contentTypes/")) continue;
+      const refContentType = d.$ref.replace("#/contentTypes/", "");
+      const refEntries = contentTypes.get(refContentType);
       if (!refEntries) continue;
 
       for (const entry of entries) {

package/src/site/context-injection.js

@@ -4,15 +4,15 @@
  * Injects project-level and page-level context variables into a page's state before compilation.
  * These are available as $site.* and $page.* in template expressions.
  *
- * Also resolves ContentCollection and ContentEntry $prototype entries against loaded content
- * collections (Phase 2, spec §6.4).
+ * Also resolves ContentCollection and ContentEntry $prototype entries against loaded content types
+ * (Phase 2, spec §6.4).
  *
  * Per site-architecture spec §10: $site.name — from project.json name $site.url — from project.json
  * url $site.state.* — site-wide reactive state $page.url — current page URL path $page.title — page
  * title $page.params — dynamic route parameters (if any)
  */
 
-import { queryCollection, findEntry } from "./content-loader.js";
+import { queryContentType, findEntry } from "./content-loader.js";
 import { resolve, dirname, relative } from "node:path";
 
 /**
@@ -21,7 +21,7 @@ import { resolve, dirname, relative } from "node:path";
  * @param {any} doc - The page document (mutated)
  * @param {any} projectConfig - Loaded project configuration
  * @param {any} route - The resolved route for this page
- * @param {Map<string, any[]>} [collections] - Loaded content collections
+ * @param {Map<string, any[]>} [contentTypes] - Loaded content types
  * @param {string | null} [projectRoot] - Absolute path to the project root (for import rebasing)
  * @returns {any} The mutated document
  */
@@ -29,7 +29,7 @@ export function injectContext(
   doc,
   projectConfig,
   route,
-  collections = new Map(),
+  contentTypes = new Map(),
   projectRoot = null,
 ) {
   if (!doc.state) doc.state = {};
@@ -49,8 +49,8 @@ export function injectContext(
   };
 
   // Resolve ContentCollection and ContentEntry $prototype entries
-  if (collections.size > 0) {
-    resolveContentPrototypes(doc.state, collections, route._pathParams ?? {});
+  if (contentTypes.size > 0) {
+    resolveContentPrototypes(doc.state, contentTypes, route._pathParams ?? {});
   }
 
   // Merge project-level state into page state (page wins on conflicts)
@@ -110,33 +110,33 @@ export function injectContext(
 /**
  * Resolve ContentCollection and ContentEntry $prototype state entries.
  *
- * Replaces state entries like: { "$prototype": "ContentCollection", "collection": "blog", ... }
- * with the actual resolved collection data.
+ * Replaces state entries like: { "$prototype": "ContentCollection", "contentType": "blog", ... }
+ * with the actual resolved content type data.
  *
  * @param {Record<string, any>} state - Page state (mutated)
- * @param {Map<string, any[]>} collections - Loaded collections
+ * @param {Map<string, any[]>} contentTypes - Loaded content types
  * @param {Record<string, any>} params - Route parameters for $ref resolution
  */
-function resolveContentPrototypes(state, collections, params) {
+function resolveContentPrototypes(state, contentTypes, params) {
   for (const [key, value] of Object.entries(state)) {
     if (!value || typeof value !== "object" || !value.$prototype) continue;
 
     if (value.$prototype === "ContentCollection") {
-      const entries = collections.get(value.collection);
+      const entries = contentTypes.get(value.contentType);
       if (!entries) {
-        console.warn(`ContentCollection: collection "${value.collection}" not found`);
+        console.warn(`ContentCollection: content type "${value.contentType}" not found`);
         state[key] = [];
         continue;
       }
-      state[key] = queryCollection(entries, {
+      state[key] = queryContentType(entries, {
         filter: value.filter,
         sort: value.sort,
         limit: value.limit,
       });
     } else if (value.$prototype === "ContentEntry") {
-      const entries = collections.get(value.collection);
+      const entries = contentTypes.get(value.contentType);
       if (!entries) {
-        console.warn(`ContentEntry: collection "${value.collection}" not found`);
+        console.warn(`ContentEntry: content type "${value.contentType}" not found`);
         state[key] = null;
         continue;
       }

package/src/site/pages-discovery.js

@@ -162,17 +162,17 @@ function fileToRoute(relativePath, absolutePath) {
 /**
  * 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:
+ * Supports three $paths shapes (per spec §4.3): 1. Content type-based: { contentType: "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)
+ * @param {Map<string, any[]>} [contentTypes] - Loaded content types (from content-loader)
  * @returns {Promise<Route[]>} Expanded routes with concrete paths
  */
-export async function expandDynamicRoutes(routes, projectRoot, collections = new Map()) {
+export async function expandDynamicRoutes(routes, projectRoot, contentTypes = new Map()) {
   /** @type {Route[]} */
   const expanded = [];
 
@@ -197,7 +197,7 @@ export async function expandDynamicRoutes(routes, projectRoot, collections = new
       continue;
     }
 
-    const pathEntries = resolvePathEntries(raw.$paths, projectRoot, collections);
+    const pathEntries = resolvePathEntries(raw.$paths, projectRoot, contentTypes);
 
     for (const pathEntry of pathEntries) {
       let concreteUrl = route.urlPattern;
@@ -225,21 +225,21 @@ export async function expandDynamicRoutes(routes, projectRoot, collections = new
  *
  * @param {any} $paths - The $paths declaration
  * @param {string} projectRoot
- * @param {Map<string, any[]>} collections
+ * @param {Map<string, any[]>} contentTypes
  * @returns {Record<string, any>[]} Array of { paramName: value } objects
  */
-function resolvePathEntries($paths, projectRoot, collections) {
+function resolvePathEntries($paths, projectRoot, contentTypes) {
   // 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);
+  // Content type-based: { contentType: "blog", param: "slug", field: "id" }
+  if ($paths.contentType) {
+    const entries = contentTypes.get($paths.contentType);
     if (!entries || entries.length === 0) {
       console.warn(
-        `Warning: $paths references collection "${$paths.collection}" but it has no entries`,
+        `Warning: $paths references content type "${$paths.contentType}" but it has no entries`,
       );
       return [];
     }

package/src/site/site-build.js

@@ -40,7 +40,7 @@ import {
   DEFAULT_REACTIVITY_SRC,
   DEFAULT_LIT_HTML_SRC,
 } from "../shared.js";
-import { loadCollections, loadContentConfig, resolveCollectionRefs } from "./content-loader.js";
+import { loadContentTypes, loadContentConfig, resolveContentTypeRefs } from "./content-loader.js";
 import { resolvePrototypes } from "./prototype-resolver.js";
 import { compileMarkdown } from "../targets/compile-markdown.js";
 import { transformImageNodes } from "./image-transform.js";
@@ -97,20 +97,20 @@ export async function buildSite(projectRoot, options = {}) {
   const staticRoutes = discoverPages(pagesDir);
   log(`  Found ${staticRoutes.length} page(s)`);
 
-  // ── 3b. Load content collections ──────────────────────────────────────
-  log("Loading content collections...");
-  const collections = await loadCollections(projectRoot, projectConfig);
-  if (collections.size > 0) {
-    log(`  Loaded ${collections.size} collection(s): ${[...collections.keys()].join(", ")}`);
-    // Resolve cross-collection $ref references
+  // ── 3b. Load content types ─────────────────────────────────────────────
+  log("Loading content types...");
+  const contentTypes = await loadContentTypes(projectRoot, projectConfig);
+  if (contentTypes.size > 0) {
+    log(`  Loaded ${contentTypes.size} content type(s): ${[...contentTypes.keys()].join(", ")}`);
+    // Resolve cross-content-type $ref references
     const contentConfig = loadContentConfig(projectRoot, projectConfig);
     if (contentConfig) {
-      resolveCollectionRefs(collections, contentConfig.config);
+      resolveContentTypeRefs(contentTypes, contentConfig.config);
     }
   }
 
   // ── 4. Expand dynamic routes ────────────────────────────────────────────
-  const routes = await expandDynamicRoutes(staticRoutes, projectRoot, collections);
+  const routes = await expandDynamicRoutes(staticRoutes, projectRoot, contentTypes);
   log(`  ${routes.length} route(s) after expansion`);
 
   let fileCount = 0;
@@ -194,7 +194,7 @@ export async function buildSite(projectRoot, options = {}) {
         route,
         projectConfig,
         projectRoot,
-        collections,
+        contentTypes,
         imageCache,
         outDir,
         componentDefs,
@@ -339,7 +339,7 @@ export async function buildSite(projectRoot, options = {}) {
  * @param {any} route
  * @param {any} projectConfig
  * @param {string} projectRoot
- * @param {Map<string, any[]>} [collections]
+ * @param {Map<string, any[]>} [contentTypes]
  * @param {import("./image-cache.js").CacheManifest | null} [imageCache]
  * @param {string} [outDir]
  * @returns {Promise<{ html: string; files: any[]; serverHandler: string | null; doc: any }>}
@@ -348,7 +348,7 @@ async function compilePage(
   route,
   projectConfig,
   projectRoot,
-  collections = new Map(),
+  contentTypes = new Map(),
   imageCache = null,
   outDir = "",
   componentDefs = new Map(),
@@ -375,7 +375,7 @@ async function compilePage(
   delete layoutDoc._pageTitle;
 
   // Inject $site and $page context, resolve ContentCollection/ContentEntry
-  injectContext(layoutDoc, projectConfig, route, collections, projectRoot);
+  injectContext(layoutDoc, projectConfig, route, contentTypes, projectRoot);
 
   // Resolve generic $prototype entries via .class.json imports
   await resolvePrototypes(layoutDoc, route, projectRoot);

package/src/site/site-loader.js

@@ -25,7 +25,7 @@ const DEFAULTS = {
   $media: {},
   style: {},
   state: {},
-  collections: {},
+  contentTypes: {},
   redirects: {},
   images: {
     optimize: true,
@@ -85,7 +85,7 @@ export function loadProjectConfig(projectRoot) {
   if (raw.state) config.state = raw.state;
   if (raw.redirects) config.redirects = raw.redirects;
   if (raw.imports) config.imports = raw.imports;
-  if (raw.collections) config.collections = raw.collections;
+  if (raw.contentTypes) config.contentTypes = raw.contentTypes;
 
   return {
     config,