js-template-engine 1.0.0 → 2.0.0

package/dist/program.d.ts

@@ -0,0 +1,16 @@
+import { Command } from 'commander';
+import { type StylingName } from './extensions';
+/**
+ * Parses the `--styling` value: a comma-separated list of styling
+ * extension names, kept in the order given.
+ *
+ * @param value - The raw flag value, e.g. `'bem,tailwind'`.
+ * @returns The styling extension names.
+ */
+export declare function parseStylingList(value: string): StylingName[];
+/**
+ * Creates the `js-template-engine` command-line program.
+ *
+ * @returns The configured program; call `parseAsync` to run it.
+ */
+export declare function createProgram(): Command;

package/dist/program.js

@@ -0,0 +1,74 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseStylingList = parseStylingList;
+exports.createProgram = createProgram;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const commander_1 = require("commander");
+const render_1 = require("./commands/render");
+const validate_1 = require("./commands/validate");
+const extensions_1 = require("./extensions");
+const outputStrategies = ['inline', 'in-file', 'separate-file'];
+/**
+ * Parses the `--styling` value: a comma-separated list of styling
+ * extension names, kept in the order given.
+ *
+ * @param value - The raw flag value, e.g. `'bem,tailwind'`.
+ * @returns The styling extension names.
+ */
+function parseStylingList(value) {
+    const names = value
+        .split(',')
+        .map((name) => name.trim())
+        .filter((name) => name.length > 0);
+    for (const name of names) {
+        if (!extensions_1.stylingNames.includes(name)) {
+            throw new commander_1.InvalidArgumentError(`Unknown styling extension '${name}'. Allowed choices are ${extensions_1.stylingNames.join(', ')}.`);
+        }
+    }
+    return names;
+}
+/**
+ * Creates the `js-template-engine` command-line program.
+ *
+ * @returns The configured program; call `parseAsync` to run it.
+ */
+function createProgram() {
+    const { version } = JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(__dirname, '..', 'package.json'), 'utf8'));
+    const program = new commander_1.Command();
+    program
+        .name('js-template-engine')
+        .description('Render data-defined component templates to HTML, React, Vue, or Svelte')
+        .version(version);
+    program
+        .command('render')
+        .description('Render a template file, or every template in a directory, to output files')
+        .argument('<source>', 'template file or directory of template files')
+        .addOption(new commander_1.Option('--framework <name>', 'framework to render with; omitted renders HTML').choices(extensions_1.frameworkNames))
+        .option('--styling <names>', `comma-separated styling extensions (${extensions_1.stylingNames.join(', ')}), applied in order`, parseStylingList, [])
+        .option('-o, --output-directory <path>', 'directory generated files are written to', './output')
+        .option('-n, --component-name <name>', 'component name for templates that declare none; defaults to the source filename in PascalCase')
+        .addOption(new commander_1.Option('--styling-strategy <strategy>', 'style output strategy')
+        .choices(outputStrategies)
+        .default('in-file'))
+        .addOption(new commander_1.Option('--styling-language <language>', 'stylesheet output language')
+        .choices(['css', 'scss'])
+        .default('css'))
+        .addOption(new commander_1.Option('--scripting-strategy <strategy>', 'script output strategy')
+        .choices(outputStrategies)
+        .default('in-file'))
+        .addOption(new commander_1.Option('--scripting-language <language>', 'script output language')
+        .choices(['javascript', 'typescript'])
+        .default('javascript'))
+        .option('--bem-element-separator <separator>', "separator between BEM block and element (default '__')")
+        .option('--bem-modifier-separator <separator>', "separator before a BEM modifier (default '--')")
+        .addOption(new commander_1.Option('--tailwind-output <output>', "what the Tailwind extension contributes: utility classes, or styles converted from them (default 'classes')").choices(['classes', 'styles']))
+        .option('--tailwind-convert-styles', "convert each element's authored style into Tailwind utility classes")
+        .action(render_1.renderCommand);
+    program
+        .command('validate')
+        .description('Validate a template file, or every template in a directory')
+        .argument('<source>', 'template file or directory of template files')
+        .action(validate_1.validateCommand);
+    return program;
+}

package/dist/reporting.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The label a source file is reported under: its path relative to the
+ * working directory, falling back to the absolute path outside of it.
+ *
+ * @param filePath - Absolute path of the source file.
+ * @returns The display label.
+ */
+export declare function sourceLabel(filePath: string): string;
+/**
+ * Formats a thrown value for the error stream.
+ *
+ * @param error - The thrown value.
+ * @returns Its message.
+ */
+export declare function formatError(error: unknown): string;

package/dist/reporting.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sourceLabel = sourceLabel;
+exports.formatError = formatError;
+const node_path_1 = require("node:path");
+/**
+ * The label a source file is reported under: its path relative to the
+ * working directory, falling back to the absolute path outside of it.
+ *
+ * @param filePath - Absolute path of the source file.
+ * @returns The display label.
+ */
+function sourceLabel(filePath) {
+    const relativePath = (0, node_path_1.relative)(process.cwd(), filePath);
+    return relativePath === '' || relativePath.startsWith('..')
+        ? filePath
+        : relativePath;
+}
+/**
+ * Formats a thrown value for the error stream.
+ *
+ * @param error - The thrown value.
+ * @returns Its message.
+ */
+function formatError(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/template-sources.d.ts

@@ -0,0 +1,22 @@
+import type { Template } from '@js-template-engine/types';
+/**
+ * Resolves a source argument to the template files it names.
+ *
+ * A file path resolves to itself; a directory resolves to every template
+ * file directly inside it (`.json`, `.ts`, `.js`, `.mjs`, `.cjs`), sorted
+ * by name. Subdirectories are not searched.
+ *
+ * @param source - A template file or a directory of template files.
+ * @returns Absolute paths of the template files to process.
+ */
+export declare function resolveTemplateSources(source: string): string[];
+/**
+ * Loads a template from a file.
+ *
+ * `.json` files are parsed as JSON. `.ts`, `.js`, `.mjs`, and `.cjs` files
+ * are loaded as modules and must default-export the template.
+ *
+ * @param filePath - Absolute path of the template file.
+ * @returns The template the file defines.
+ */
+export declare function loadTemplate(filePath: string): Promise<Template>;

package/dist/template-sources.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveTemplateSources = resolveTemplateSources;
+exports.loadTemplate = loadTemplate;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const jiti_1 = require("jiti");
+/** The file extensions recognized as template sources. */
+const templateFileExtensions = ['.json', '.ts', '.js', '.mjs', '.cjs'];
+const jiti = (0, jiti_1.createJiti)(__filename, { interopDefault: true });
+/**
+ * Resolves a source argument to the template files it names.
+ *
+ * A file path resolves to itself; a directory resolves to every template
+ * file directly inside it (`.json`, `.ts`, `.js`, `.mjs`, `.cjs`), sorted
+ * by name. Subdirectories are not searched.
+ *
+ * @param source - A template file or a directory of template files.
+ * @returns Absolute paths of the template files to process.
+ */
+function resolveTemplateSources(source) {
+    const absolute = (0, node_path_1.resolve)(source);
+    if (!(0, node_fs_1.existsSync)(absolute)) {
+        throw new Error(`Template source '${source}' does not exist`);
+    }
+    if ((0, node_fs_1.statSync)(absolute).isFile()) {
+        return [absolute];
+    }
+    const files = (0, node_fs_1.readdirSync)(absolute, { withFileTypes: true })
+        .filter((entry) => entry.isFile() &&
+        templateFileExtensions.includes((0, node_path_1.extname)(entry.name)) &&
+        !entry.name.endsWith('.d.ts'))
+        .map((entry) => (0, node_path_1.join)(absolute, entry.name))
+        .sort();
+    if (files.length === 0) {
+        throw new Error(`No template files found in '${source}'`);
+    }
+    return files;
+}
+/**
+ * Loads a template from a file.
+ *
+ * `.json` files are parsed as JSON. `.ts`, `.js`, `.mjs`, and `.cjs` files
+ * are loaded as modules and must default-export the template.
+ *
+ * @param filePath - Absolute path of the template file.
+ * @returns The template the file defines.
+ */
+async function loadTemplate(filePath) {
+    if ((0, node_path_1.extname)(filePath) === '.json') {
+        return JSON.parse((0, node_fs_1.readFileSync)(filePath, 'utf8'));
+    }
+    const template = await jiti.import(filePath, { default: true });
+    if (!isTemplateShaped(template)) {
+        throw new Error(`'${filePath}' does not default-export a template`);
+    }
+    return template;
+}
+/**
+ * Whether a module's default export has a template's root shape — a node
+ * array or a node object. Modules without a default export resolve to
+ * their namespace object, which this rules out.
+ */
+function isTemplateShaped(value) {
+    if (Array.isArray(value)) {
+        return true;
+    }
+    return (typeof value === 'object' &&
+        value !== null &&
+        typeof value.type === 'string');
+}

package/package.json

@@ -1,42 +1,66 @@
 {
   "name": "js-template-engine",
-  "version": "1.0.0",
-  "description": "A dynamic templating engine that translates JavaScript or JSON data into structured templates across multiple languages.",
-  "main": "index.js",
+  "version": "2.0.0",
+  "description": "Command-line interface for the JS Template Engine: render data-defined component templates to HTML, React, Vue, or Svelte",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
   "bin": {
-    "js-template-engine": "./bin/cli.js"
+    "js-template-engine": "./dist/cli.js"
   },
-  "scripts": {
-    "example:react": "node examples/react.js",
-    "example:bem": "node examples/bem.js",
-    "example:slots": "node examples/slots.js"
+  "dependencies": {
+    "commander": "^12.1.0",
+    "jiti": "^2.4.2",
+    "@js-template-engine/core": "^2.0.0",
+    "@js-template-engine/extension-bem": "^2.0.0",
+    "@js-template-engine/extension-react": "^2.0.0",
+    "@js-template-engine/extension-tailwind": "^2.0.0",
+    "@js-template-engine/extension-vue": "^2.0.0",
+    "@js-template-engine/extension-svelte": "^2.0.0",
+    "@js-template-engine/types": "^2.0.0"
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/djurnamn/js-template-engine.git"
+    "url": "git+https://github.com/djurnamn/js-template-engine.git",
+    "directory": "packages/cli"
   },
   "keywords": [
-    "javascript",
-    "js",
+    "js-template-engine",
+    "cli",
     "template",
-    "templating",
-    "engine",
-    "json",
+    "code-generation",
     "react",
-    "bem"
+    "vue",
+    "svelte"
   ],
   "author": "Björn Djurnamn <bjorn@djurnamn.co>",
   "license": "MIT",
   "bugs": {
     "url": "https://github.com/djurnamn/js-template-engine/issues"
   },
-  "homepage": "https://github.com/djurnamn/js-template-engine",
-  "dependencies": {
-    "signale": "^1.4.0",
-    "yargs": "^17.7.2"
-  },
+  "homepage": "https://github.com/djurnamn/js-template-engine/tree/main/packages/cli",
   "devDependencies": {
-    "eslint": "^8.0.1",
-    "prettier": "^3.2.5"
+    "@types/node": "^20.0.0",
+    "rimraf": "^5.0.5",
+    "typescript": "^5.3.3",
+    "vitest": "^1.6.1"
+  },
+  "scripts": {
+    "build": "tsc",
+    "build:watch": "tsc --watch",
+    "clean": "rimraf dist",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "type-check": "tsc --noEmit -p tsconfig.type-check.json"
   }
-}
+}

package/.eslintrc.js

@@ -1,26 +0,0 @@
-module.exports = {
-  env: {
-    node: true,
-    browser: true,
-    commonjs: true,
-    es2021: true,
-  },
-  extends: "eslint:recommended",
-  overrides: [
-    {
-      env: {
-        node: true,
-      },
-      files: [".eslintrc.{js,cjs}"],
-      parserOptions: {
-        sourceType: "script",
-      },
-    },
-  ],
-  parserOptions: {
-    ecmaVersion: "latest",
-  },
-  rules: {
-    "no-unused-vars": ["error", { argsIgnorePattern: "^_" }],
-  },
-};

package/bin/cli.js

@@ -1,129 +0,0 @@
-#!/usr/bin/env node
-
-const fs = require("fs");
-const path = require("path");
-const process = require("process");
-const yargs = require("yargs/yargs");
-const { hideBin } = require("yargs/helpers");
-const TemplateEngine = require("../src/engine/TemplateEngine");
-const {
-  getSourcePathType,
-  processFile,
-  processDirectory,
-} = require("../src/handlers/FileHandler");
-const createLogger = require("../src/helpers/createLogger");
-
-function loadExtensions() {
-  const extensions = {};
-  const fullPath = path.join(__dirname, "..", "src", "extensions");
-
-  fs.readdirSync(fullPath).forEach((file) => {
-    if (path.extname(file) !== ".js") return;
-
-    const extName = path.basename(file, ".js");
-    const ExtensionClass = require(path.join(fullPath, file));
-    extensions[extName] = ExtensionClass;
-  });
-
-  return extensions;
-}
-
-const availableExtensions = loadExtensions();
-
-// Utility function for error handling and extension validation
-function validateExtensions(requestedExtensions, availableExtensions) {
-  const missingExtensions = requestedExtensions.filter(
-    (ext) => !availableExtensions[ext]
-  );
-  if (missingExtensions.length > 0) {
-    console.error(
-      "One or more specified extensions could not be loaded:",
-      missingExtensions.join(", ")
-    );
-    return false;
-  }
-  return true;
-}
-
-yargs(hideBin(process.argv))
-  .command(
-    "render <sourcePath> [options]",
-    "Render templates from JSON to HTML/JSX",
-    (yargs) => {
-      yargs
-        .positional("sourcePath", {
-          describe: "Source file or directory containing JSON templates",
-          type: "string",
-        })
-        .option("outputDir", {
-          alias: "o",
-          describe: "Output directory for rendered templates",
-          type: "string",
-        })
-        .option("extensions", {
-          alias: "e",
-          describe: "Extensions to use for template processing",
-          type: "array",
-          default: [],
-        })
-        .option("name", {
-          alias: "n",
-          describe: "Base name for output files",
-          type: "string",
-        })
-        .option("componentName", {
-          alias: "c",
-          describe: "Component name for framework-specific templates",
-          type: "string",
-        })
-        .option("verbose", {
-          alias: "v",
-          type: "boolean",
-          description: "Run with verbose logging",
-        });
-    },
-    async (argv) => {
-      const { verbose } = argv;
-      const logger = createLogger(verbose, "cli");
-      logger.info("Starting template rendering process...");
-
-      // Validate requested extensions before attempting to use them
-      if (!validateExtensions(argv.extensions, availableExtensions)) {
-        // Exit if validation fails
-        return;
-      }
-
-      // Instantiate extensions with verbosity
-      const extensions = argv.extensions.map(
-        (extension) => new availableExtensions[extension](verbose)
-      );
-
-      const { name, componentName } = argv;
-      const sourcePath = path.join(process.cwd(), argv.sourcePath);
-      const outputDir = argv.outputDir ?? "";
-      const sourcePathType = await getSourcePathType(sourcePath);
-      const templateEngine = new TemplateEngine();
-
-      if (sourcePathType === "directory") {
-        await processDirectory(
-          sourcePath,
-          outputDir,
-          extensions,
-          templateEngine,
-          verbose
-        );
-      } else if (sourcePathType === "file") {
-        await processFile(
-          sourcePath,
-          outputDir,
-          extensions,
-          templateEngine,
-          name,
-          componentName,
-          verbose
-        );
-      }
-    }
-  )
-  .demandCommand(1, "You need at least one command before moving on")
-  .help().argv;

package/dist/bem.html

@@ -1,12 +0,0 @@
-<nav class="nav">
-  <ul class="nav__list">
-    <li class="nav__item nav__item--active">
-      <a href="/" class="nav__link"><span class="nav__link-text">Home</span></a>
-    </li>
-    <li class="nav__item">
-      <a href="/about" class="nav__link"
-        ><span class="nav__link-text">About</span></a
-      >
-    </li>
-  </ul>
-</nav>

package/examples/bem.js

@@ -1,81 +0,0 @@
-// Example of using the TemplateEngine class to render a simple HTML template with a class naming convention using the BEM extension.
-// You can run this example with `npm run example:slots` or `yarn example:slots`.
-
-const { TemplateEngine, BemExtension } = require("../src");
-const verbose = true;
-
-const templateEngine = new TemplateEngine();
-const bemExtension = new BemExtension(verbose);
-
-const bem = bemExtension.setNodeExtensionOptionsShortcut;
-
-/*
-Using the BEM extension options shortcut allows us to write:
-
-{
-  tag: "nav",
-  ...bem({ block: "nav" }),
-}
-
-instead of:
-
-{
-  tag: "nav",
-  extensions: {
-    bem: {
-      block: "nav",
-    },
-  },
-}
-*/
-
-// Data
-const navigationItems = [
-  { name: "Home", url: "/", iconName: "home" },
-  { name: "About", url: "/about", iconName: "about" },
-];
-
-// Templates
-const navigationTemplate = [
-  {
-    tag: "nav",
-    ...bem({ block: "nav" }),
-    children: [
-      {
-        tag: "ul",
-        ...bem({ element: "list" }),
-        children: navigationItems.map((item, itemIndex) => ({
-          tag: "li",
-          ...bem({
-            element: "item",
-            modifiers: itemIndex === 0 ? ["active"] : [],
-          }),
-          children: [
-            {
-              tag: "a",
-              ...bem({ element: "link" }),
-              attributes: { href: item.url },
-              children: [
-                {
-                  tag: "span",
-                  ...bem({ element: "link-text" }),
-                  children: [{ type: "text", content: item.name }],
-                },
-              ],
-            },
-          ],
-        })),
-      },
-    ],
-  },
-];
-
-// Render
-(async () => {
-  await templateEngine.render(navigationTemplate, {
-    name: "bem",
-    extensions: [bemExtension], // Only BEM extension is needed for this example
-    writeOutputFile: true,
-    verbose,
-  });
-})();

package/examples/react.js

@@ -1,109 +0,0 @@
-// Example of using the TemplateEngine class to render a simple JSX component with using the React extension.
-// You can run this example with `npm run example:react` or `yarn example:react`.
-
-const { TemplateEngine, ReactExtension } = require("../src");
-const verbose = true;
-
-const templateEngine = new TemplateEngine();
-const reactExtension = new ReactExtension(verbose);
-
-const initialTodos = [
-  { id: 1, text: "Learn JavaScript", completed: false },
-  { id: 2, text: "Build a todo app", completed: false },
-];
-
-const todoAppTemplate = [
-  {
-    tag: "div",
-    attributes: { class: "todo-app" },
-    children: [
-      {
-        tag: "input",
-        attributes: {
-          type: "text",
-          id: "todoInput",
-          placeholder: "Add a new todo",
-        },
-      },
-      {
-        tag: "button",
-        attributes: {
-          onclick: "handleAddTodo",
-        },
-        children: [{ type: "text", content: "Add" }],
-        extensions: {
-          react: {
-            tag: "DefaultButton",
-            attributes: {
-              color: "primary",
-              label: "Add",
-            },
-            expressionAttributes: {
-              onClick: "handleAddTodo",
-            },
-          },
-        },
-      },
-      {
-        tag: "ul",
-        attributes: { id: "todoList" },
-        children: initialTodos.map((todo) => ({
-          tag: "li",
-          children: [{ type: "text", content: todo.text }],
-          attributes: {
-            onclick: "this.parentNode.removeChild(this);",
-          },
-          extensions: {
-            react: {
-              tag: "TodoCard",
-              expressionAttributes: {
-                onClick: "() => handleRemoveTodo()",
-              },
-            },
-          },
-        })),
-      },
-      {
-        tag: "script",
-        children: [
-          {
-            type: "text",
-            content: `
-                function handleAddTodo() {
-                    const todoList = document.getElementById('todoList');
-                    const newTodoText = document.getElementById('todoInput').value;
-                    const newTodoItem = document.createElement('li');
-                    
-                    newTodoItem.textContent = newTodoText;
-                    todoList.appendChild(newTodoItem);
-                    
-                    document.getElementById('todoInput').value = ''; // Clear the input field
-                }
-            `,
-          },
-        ],
-        extensions: {
-          react: {
-            ignore: true,
-          },
-        },
-      },
-    ],
-  },
-];
-
-// Render
-(async () => {
-  await templateEngine.render(todoAppTemplate, {
-    name: "html-todo-app",
-    writeOutputFile: true,
-  });
-
-  await templateEngine.render(todoAppTemplate, {
-    name: "react-todo-app",
-    extensions: [reactExtension], // Only React extension is needed for this example
-    outputDir: "dist", // React extension defaults to "dist/react"
-    writeOutputFile: true,
-    verbose,
-  });
-})();