pulse-js-framework 1.4.10 → 1.5.0

package/compiler/transformer/index.js

@@ -0,0 +1,319 @@
+/**
+ * Pulse Transformer - Code generator
+ *
+ * Transforms AST into JavaScript code
+ *
+ * Features:
+ * - Import statement support
+ * - Slot-based component composition
+ * - CSS scoping with unique class prefixes
+ * - Source map generation
+ *
+ * @module pulse-js-framework/compiler/transformer
+ */
+
+import { SourceMapGenerator } from '../sourcemap.js';
+import { generateScopeId } from './constants.js';
+import { extractImportedComponents, generateImports } from './imports.js';
+import {
+  extractPropVars,
+  extractStateVars,
+  extractActionNames,
+  transformState,
+  transformActions,
+  transformValue
+} from './state.js';
+import { transformRouter } from './router.js';
+import { transformStore } from './store.js';
+import { transformExpression, transformExpressionString, transformFunctionBody } from './expressions.js';
+import { transformView, transformViewNode, VIEW_NODE_HANDLERS, addScopeToSelector } from './view.js';
+import { transformStyle, transformStyleRule, scopeStyleSelector } from './style.js';
+import { generateExport } from './export.js';
+
+/**
+ * Transformer class
+ */
+export class Transformer {
+  constructor(ast, options = {}) {
+    this.ast = ast;
+    // Default to source maps enabled in development mode
+    const isDev = typeof process !== 'undefined' && process.env?.NODE_ENV !== 'production';
+    this.options = {
+      runtime: 'pulse-js-framework/runtime',
+      minify: false,
+      scopeStyles: true,
+      sourceMap: isDev,        // Enable source map generation (default: true in dev)
+      sourceFileName: null,    // Original .pulse file name
+      sourceContent: null,     // Original source content (for inline source maps)
+      ...options
+    };
+    this.stateVars = new Set();
+    this.propVars = new Set();
+    this.propDefaults = new Map();
+    this.actionNames = new Set();
+    this.importedComponents = new Map();
+    this.scopeId = this.options.scopeStyles ? generateScopeId() : null;
+
+    // Source map tracking
+    this.sourceMap = null;
+    this._currentLine = 0;
+    this._currentColumn = 0;
+
+    // Initialize source map generator if enabled
+    if (this.options.sourceMap) {
+      this.sourceMap = new SourceMapGenerator({
+        file: this.options.sourceFileName?.replace('.pulse', '.js') || 'output.js'
+      });
+      if (this.options.sourceFileName) {
+        this.sourceMap.addSource(
+          this.options.sourceFileName,
+          this.options.sourceContent
+        );
+      }
+    }
+  }
+
+  /**
+   * Add a mapping to the source map
+   * @param {Object} original - Original position {line, column} (1-based)
+   * @param {string} name - Optional identifier name
+   */
+  _addMapping(original, name = null) {
+    if (!this.sourceMap || !original) return;
+
+    this.sourceMap.addMapping({
+      generated: {
+        line: this._currentLine,
+        column: this._currentColumn
+      },
+      original: {
+        line: original.line - 1, // Convert to 0-based
+        column: original.column - 1
+      },
+      source: this.options.sourceFileName,
+      name
+    });
+  }
+
+  /**
+   * Track output position when writing code
+   * @param {string} code - Generated code
+   * @returns {string} The same code (for chaining)
+   */
+  _trackCode(code) {
+    for (const char of code) {
+      if (char === '\n') {
+        this._currentLine++;
+        this._currentColumn = 0;
+      } else {
+        this._currentColumn++;
+      }
+    }
+    return code;
+  }
+
+  /**
+   * Write code with optional source mapping
+   * @param {string} code - Code to write
+   * @param {Object} original - Original position {line, column}
+   * @param {string} name - Optional identifier name
+   * @returns {string} The code
+   */
+  _emit(code, original = null, name = null) {
+    if (original) {
+      this._addMapping(original, name);
+    }
+    return this._trackCode(code);
+  }
+
+  /**
+   * Transform AST to JavaScript code
+   */
+  transform() {
+    const parts = [];
+
+    // Extract imported components first
+    if (this.ast.imports) {
+      extractImportedComponents(this, this.ast.imports);
+    }
+
+    // Imports (runtime + user imports)
+    parts.push(generateImports(this));
+
+    // Extract prop variables
+    if (this.ast.props) {
+      extractPropVars(this, this.ast.props);
+    }
+
+    // Extract state variables
+    if (this.ast.state) {
+      extractStateVars(this, this.ast.state);
+    }
+
+    // Extract action names
+    if (this.ast.actions) {
+      extractActionNames(this, this.ast.actions);
+    }
+
+    // Store (must come before router so $store is available to guards)
+    if (this.ast.store) {
+      parts.push(transformStore(this, this.ast.store, transformValue));
+    }
+
+    // Router (after store so guards can access $store)
+    if (this.ast.router) {
+      parts.push(transformRouter(this, this.ast.router));
+    }
+
+    // State
+    if (this.ast.state) {
+      parts.push(transformState(this, this.ast.state));
+    }
+
+    // Actions
+    if (this.ast.actions) {
+      parts.push(transformActions(this, this.ast.actions, transformFunctionBody));
+    }
+
+    // View
+    if (this.ast.view) {
+      parts.push(transformView(this, this.ast.view));
+    }
+
+    // Style
+    if (this.ast.style) {
+      parts.push(transformStyle(this, this.ast.style));
+    }
+
+    // Component export
+    parts.push(generateExport(this));
+
+    const code = parts.filter(Boolean).join('\n\n');
+
+    // Track the generated code for source map positions
+    if (this.sourceMap) {
+      this._trackCode(code);
+    }
+
+    return code;
+  }
+
+  /**
+   * Transform AST and return result with optional source map
+   * @returns {Object} Result with code and optional sourceMap
+   */
+  transformWithSourceMap() {
+    const code = this.transform();
+
+    if (!this.sourceMap) {
+      return { code, sourceMap: null };
+    }
+
+    return {
+      code,
+      sourceMap: this.sourceMap.toJSON(),
+      sourceMapComment: this.sourceMap.toComment()
+    };
+  }
+
+  // =============================================================================
+  // Instance methods that delegate to module functions
+  // These are kept for backward compatibility
+  // =============================================================================
+
+  extractImportedComponents(imports) {
+    return extractImportedComponents(this, imports);
+  }
+
+  generateImports() {
+    return generateImports(this);
+  }
+
+  extractPropVars(propsBlock) {
+    return extractPropVars(this, propsBlock);
+  }
+
+  extractStateVars(stateBlock) {
+    return extractStateVars(this, stateBlock);
+  }
+
+  extractActionNames(actionsBlock) {
+    return extractActionNames(this, actionsBlock);
+  }
+
+  transformState(stateBlock) {
+    return transformState(this, stateBlock);
+  }
+
+  transformRouter(routerBlock) {
+    return transformRouter(this, routerBlock);
+  }
+
+  transformStore(storeBlock) {
+    return transformStore(this, storeBlock, transformValue);
+  }
+
+  transformValue(node) {
+    return transformValue(this, node);
+  }
+
+  transformActions(actionsBlock) {
+    return transformActions(this, actionsBlock, transformFunctionBody);
+  }
+
+  transformFunctionBody(tokens) {
+    return transformFunctionBody(this, tokens);
+  }
+
+  transformView(viewBlock) {
+    return transformView(this, viewBlock);
+  }
+
+  transformViewNode(node, indent = 0) {
+    return transformViewNode(this, node, indent);
+  }
+
+  transformExpression(node) {
+    return transformExpression(this, node);
+  }
+
+  transformExpressionString(exprStr) {
+    return transformExpressionString(this, exprStr);
+  }
+
+  transformStyle(styleBlock) {
+    return transformStyle(this, styleBlock);
+  }
+
+  transformStyleRule(rule, indent) {
+    return transformStyleRule(this, rule, indent);
+  }
+
+  scopeStyleSelector(selector) {
+    return scopeStyleSelector(this, selector);
+  }
+
+  addScopeToSelector(selector) {
+    return addScopeToSelector(this, selector);
+  }
+
+  generateExport() {
+    return generateExport(this);
+  }
+}
+
+// Static property for VIEW_NODE_HANDLERS (backward compatibility)
+Transformer.VIEW_NODE_HANDLERS = VIEW_NODE_HANDLERS;
+
+/**
+ * Transform AST to JavaScript code
+ */
+export function transform(ast, options = {}) {
+  const transformer = new Transformer(ast, options);
+  return transformer.transform();
+}
+
+export default {
+  Transformer,
+  transform
+};

package/compiler/transformer/router.js

@@ -0,0 +1,95 @@
+/**
+ * Transformer Router Module
+ * Handles router block transformation
+ * @module pulse-js-framework/compiler/transformer/router
+ */
+
+import { PUNCT_NO_SPACE_BEFORE, PUNCT_NO_SPACE_AFTER } from './constants.js';
+
+/**
+ * Helper to emit token value with proper string/template handling
+ * @param {Object} token - Token to emit
+ * @returns {string} Token value
+ */
+export function emitToken(token) {
+  if (token.type === 'STRING') return token.raw || JSON.stringify(token.value);
+  if (token.type === 'TEMPLATE') return token.raw || ('`' + token.value + '`');
+  return token.value;
+}
+
+/**
+ * Helper to check if space needed between tokens
+ * @param {Object} token - Current token
+ * @param {Object} nextToken - Next token
+ * @returns {boolean} Whether space is needed
+ */
+export function needsSpace(token, nextToken) {
+  if (!nextToken) return false;
+  return !PUNCT_NO_SPACE_BEFORE.includes(nextToken.type) &&
+         !PUNCT_NO_SPACE_AFTER.includes(token.type);
+}
+
+/**
+ * Transform router guard body - handles store references
+ * @param {Array} tokens - Body tokens
+ * @returns {string} JavaScript code
+ */
+export function transformRouterGuardBody(tokens) {
+  let code = '';
+  for (let i = 0; i < tokens.length; i++) {
+    const token = tokens[i];
+    if (token.value === 'store' && tokens[i + 1]?.type === 'DOT') {
+      code += '$store';
+    } else {
+      code += emitToken(token);
+    }
+    if (needsSpace(token, tokens[i + 1])) code += ' ';
+  }
+  return code.trim();
+}
+
+/**
+ * Transform router block to createRouter() call
+ * @param {Object} transformer - Transformer instance
+ * @param {Object} routerBlock - Router block from AST
+ * @returns {string} JavaScript code
+ */
+export function transformRouter(transformer, routerBlock) {
+  const lines = ['// Router'];
+
+  // Build routes object
+  const routesCode = [];
+  for (const route of routerBlock.routes) {
+    routesCode.push(`    '${route.path}': ${route.handler}`);
+  }
+
+  lines.push('const router = createRouter({');
+  lines.push(`  mode: '${routerBlock.mode}',`);
+  if (routerBlock.base) {
+    lines.push(`  base: '${routerBlock.base}',`);
+  }
+  lines.push('  routes: {');
+  lines.push(routesCode.join(',\n'));
+  lines.push('  }');
+  lines.push('});');
+  lines.push('');
+
+  // Add global guards
+  if (routerBlock.beforeEach) {
+    const params = routerBlock.beforeEach.params.join(', ');
+    const body = transformRouterGuardBody(routerBlock.beforeEach.body);
+    lines.push(`router.beforeEach((${params}) => { ${body} });`);
+  }
+
+  if (routerBlock.afterEach) {
+    const params = routerBlock.afterEach.params.join(', ');
+    const body = transformRouterGuardBody(routerBlock.afterEach.body);
+    lines.push(`router.afterEach((${params}) => { ${body} });`);
+  }
+
+  lines.push('');
+  lines.push('// Start router');
+  lines.push('router.start();');
+
+  return lines.join('\n');
+}

package/compiler/transformer/state.js

@@ -0,0 +1,118 @@
+/**
+ * Transformer State Module
+ * Handles state, props, and actions extraction and transformation
+ * @module pulse-js-framework/compiler/transformer/state
+ */
+
+import { NodeType } from '../parser.js';
+
+/**
+ * Extract prop variable names and defaults
+ * @param {Object} transformer - Transformer instance
+ * @param {Object} propsBlock - Props block from AST
+ */
+export function extractPropVars(transformer, propsBlock) {
+  for (const prop of propsBlock.properties) {
+    transformer.propVars.add(prop.name);
+    transformer.propDefaults.set(prop.name, prop.value);
+  }
+}
+
+/**
+ * Extract state variable names
+ * @param {Object} transformer - Transformer instance
+ * @param {Object} stateBlock - State block from AST
+ */
+export function extractStateVars(transformer, stateBlock) {
+  for (const prop of stateBlock.properties) {
+    transformer.stateVars.add(prop.name);
+  }
+}
+
+/**
+ * Extract action names
+ * @param {Object} transformer - Transformer instance
+ * @param {Object} actionsBlock - Actions block from AST
+ */
+export function extractActionNames(transformer, actionsBlock) {
+  for (const fn of actionsBlock.functions) {
+    transformer.actionNames.add(fn.name);
+  }
+}
+
+/**
+ * Transform a value node to JavaScript code
+ * @param {Object} transformer - Transformer instance
+ * @param {Object} node - AST node to transform
+ * @returns {string} JavaScript code
+ */
+export function transformValue(transformer, node) {
+  if (!node) return 'undefined';
+
+  switch (node.type) {
+    case NodeType.Literal:
+      if (typeof node.value === 'string') {
+        return JSON.stringify(node.value);
+      }
+      return String(node.value);
+
+    case NodeType.ObjectLiteral: {
+      const props = node.properties.map(p =>
+        `${p.name}: ${transformValue(transformer, p.value)}`
+      );
+      return `{ ${props.join(', ')} }`;
+    }
+
+    case NodeType.ArrayLiteral: {
+      const elements = node.elements.map(e => transformValue(transformer, e));
+      return `[${elements.join(', ')}]`;
+    }
+
+    case NodeType.Identifier:
+      return node.name;
+
+    default:
+      return 'undefined';
+  }
+}
+
+/**
+ * Transform state block to pulse declarations
+ * @param {Object} transformer - Transformer instance
+ * @param {Object} stateBlock - State block from AST
+ * @returns {string} JavaScript code
+ */
+export function transformState(transformer, stateBlock) {
+  const lines = ['// State'];
+
+  for (const prop of stateBlock.properties) {
+    const value = transformValue(transformer, prop.value);
+    lines.push(`const ${prop.name} = pulse(${value});`);
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Transform actions block to function declarations
+ * @param {Object} transformer - Transformer instance
+ * @param {Object} actionsBlock - Actions block from AST
+ * @param {Function} transformFunctionBody - Function to transform body tokens
+ * @returns {string} JavaScript code
+ */
+export function transformActions(transformer, actionsBlock, transformFunctionBody) {
+  const lines = ['// Actions'];
+
+  for (const fn of actionsBlock.functions) {
+    const asyncKeyword = fn.async ? 'async ' : '';
+    const params = fn.params.join(', ');
+    const body = transformFunctionBody(transformer, fn.body);
+
+    lines.push(`${asyncKeyword}function ${fn.name}(${params}) {`);
+    lines.push(`  ${body}`);
+    lines.push('}');
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}

package/compiler/transformer/store.js

@@ -0,0 +1,97 @@
+/**
+ * Transformer Store Module
+ * Handles store block transformation
+ * @module pulse-js-framework/compiler/transformer/store
+ */
+
+import { emitToken, needsSpace } from './router.js';
+
+/**
+ * Transform store action body (this.x = y -> store.x.set(y))
+ * @param {Array} tokens - Body tokens
+ * @returns {string} JavaScript code
+ */
+export function transformStoreActionBody(tokens) {
+  let code = '';
+  for (let i = 0; i < tokens.length; i++) {
+    const token = tokens[i];
+    if (token.value === 'this') code += 'store';
+    else if (token.type === 'COLON') code += ' : ';
+    else code += emitToken(token);
+    if (needsSpace(token, tokens[i + 1])) code += ' ';
+  }
+  return code.replace(/store\.(\w+)\s*=\s*([^;]+)/g, 'store.$1.set($2)').trim();
+}
+
+/**
+ * Transform store getter body (this.x -> store.x.get())
+ * @param {Array} tokens - Body tokens
+ * @returns {string} JavaScript code
+ */
+export function transformStoreGetterBody(tokens) {
+  return transformStoreActionBody(tokens)
+    .replace(/store\.(\w+)(?!\.(?:get|set)\()/g, 'store.$1.get()');
+}
+
+/**
+ * Transform store block to createStore(), createActions(), createGetters() calls
+ * @param {Object} transformer - Transformer instance
+ * @param {Object} storeBlock - Store block from AST
+ * @param {Function} transformValue - Function to transform values
+ * @returns {string} JavaScript code
+ */
+export function transformStore(transformer, storeBlock, transformValue) {
+  const lines = ['// Store'];
+
+  // Transform state
+  if (storeBlock.state) {
+    const stateProps = storeBlock.state.properties.map(p =>
+      `  ${p.name}: ${transformValue(transformer, p.value)}`
+    ).join(',\n');
+
+    lines.push('const store = createStore({');
+    lines.push(stateProps);
+    lines.push('}, {');
+    lines.push(`  persist: ${storeBlock.persist},`);
+    lines.push(`  storageKey: '${storeBlock.storageKey}'`);
+    lines.push('});');
+    lines.push('');
+  }
+
+  // Transform actions
+  if (storeBlock.actions) {
+    lines.push('const storeActions = createActions(store, {');
+    for (const fn of storeBlock.actions.functions) {
+      const params = fn.params.length > 0 ? ', ' + fn.params.join(', ') : '';
+      const body = transformStoreActionBody(fn.body);
+      lines.push(`  ${fn.name}: (store${params}) => { ${body} },`);
+    }
+    lines.push('});');
+    lines.push('');
+  }
+
+  // Transform getters
+  if (storeBlock.getters) {
+    lines.push('const storeGetters = createGetters(store, {');
+    for (const getter of storeBlock.getters.getters) {
+      const body = transformStoreGetterBody(getter.body);
+      lines.push(`  ${getter.name}: (store) => { ${body} },`);
+    }
+    lines.push('});');
+    lines.push('');
+  }
+
+  // Create combined $store object for easy access
+  lines.push('// Combined store with actions and getters');
+  lines.push('const $store = {');
+  lines.push('  ...store,');
+  if (storeBlock.actions) {
+    lines.push('  ...storeActions,');
+  }
+  if (storeBlock.getters) {
+    lines.push('  ...storeGetters,');
+  }
+  lines.push('};');
+
+  return lines.join('\n');
+}