pulse-js-framework 1.10.4 → 1.11.1

package/compiler/transformer/actions.js

@@ -0,0 +1,329 @@
+/**
+ * Server Actions Compiler Support
+ *
+ * Detects and transforms Server Action functions marked with 'use server'.
+ * Generates client-side RPC stubs and server-side registration code.
+ *
+ * @module pulse-js-framework/compiler/transformer/actions
+ */
+
+// ============================================================
+// Detection
+// ============================================================
+
+/**
+ * Detect Server Action in function
+ * @param {Object} functionNode - Function AST node
+ * @returns {boolean} True if function is a Server Action
+ *
+ * @example
+ * // Function with 'use server' directive
+ * async function createUser(data) {
+ *   'use server';
+ *   return await db.users.create(data);
+ * }
+ * // isServerAction(functionNode) → true
+ */
+export function isServerAction(functionNode) {
+  // Look for 'use server' directive at top of function
+  if (!functionNode.body || !functionNode.body.length) {
+    return false;
+  }
+
+  const firstStatement = functionNode.body[0];
+  if (firstStatement.type === 'StringLiteral' || firstStatement.type === 'ExpressionStatement') {
+    const value = firstStatement.value || firstStatement.expression?.value;
+    if (typeof value === 'string') {
+      const directive = value.trim().toLowerCase();
+      return directive === 'use server';
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Check if entire module has 'use server' directive
+ * @param {Object} ast - Module AST
+ * @returns {boolean} True if module-level 'use server'
+ */
+export function hasServerDirective(ast) {
+  if (!ast.body || !ast.body.length) {
+    return false;
+  }
+
+  const firstStatement = ast.body[0];
+  if (firstStatement.type === 'StringLiteral' || firstStatement.type === 'ExpressionStatement') {
+    const value = firstStatement.value || firstStatement.expression?.value;
+    if (typeof value === 'string') {
+      const directive = value.trim().toLowerCase();
+      return directive === 'use server';
+    }
+  }
+
+  return false;
+}
+
+// ============================================================
+// Transformation
+// ============================================================
+
+/**
+ * Transform Server Action function to RPC stub
+ * @param {Object} functionNode - Function AST node
+ * @param {string} componentId - Component identifier
+ * @param {string} functionName - Function name
+ * @returns {string} Transformed JavaScript code
+ *
+ * @example
+ * // Input:
+ * async function createUser(data) {
+ *   'use server';
+ *   return await db.users.create(data);
+ * }
+ *
+ * // Output:
+ * import { createActionInvoker } from 'pulse-js-framework/runtime/server-components';
+ * const createUser = createActionInvoker('Component$createUser');
+ */
+export function transformServerAction(functionNode, componentId, functionName) {
+  const actionId = `${componentId}$${functionName}`;
+
+  // Generate client-side stub that calls server
+  return `
+// Server Action: ${functionName}
+import { createActionInvoker } from 'pulse-js-framework/runtime/server-components';
+const ${functionName} = createActionInvoker('${actionId}');
+  `.trim();
+}
+
+/**
+ * Transform module with 'use server' directive
+ * @param {string} moduleId - Module identifier
+ * @param {Array<Object>} exportedFunctions - Exported function nodes
+ * @returns {string} Transformed module code
+ *
+ * @example
+ * // Input module with 'use server':
+ * 'use server';
+ * export async function createUser(data) { ... }
+ * export async function deleteUser(id) { ... }
+ *
+ * // Output (client bundle):
+ * import { createActionInvoker } from 'pulse-js-framework/runtime/server-components';
+ * export const createUser = createActionInvoker('Module$createUser');
+ * export const deleteUser = createActionInvoker('Module$deleteUser');
+ */
+export function transformServerModule(moduleId, exportedFunctions) {
+  const imports = `import { createActionInvoker } from 'pulse-js-framework/runtime/server-components';`;
+
+  const stubs = exportedFunctions.map(fn => {
+    const actionId = `${moduleId}$${fn.name}`;
+    return `export const ${fn.name} = createActionInvoker('${actionId}');`;
+  });
+
+  return [imports, '', ...stubs].join('\n');
+}
+
+// ============================================================
+// Extraction
+// ============================================================
+
+/**
+ * Extract Server Actions from actions block
+ * @param {Object} actionsBlock - Actions block AST node
+ * @param {string} componentId - Component identifier
+ * @returns {Array<{id, name, params}>} Server Actions metadata
+ *
+ * @example
+ * // .pulse file actions block:
+ * actions {
+ *   async createUser(data) {
+ *     'use server';
+ *     return await db.users.create(data);
+ *   }
+ *   async deleteUser(id) {
+ *     'use server';
+ *     return await db.users.delete(id);
+ *   }
+ * }
+ *
+ * // extractServerActions(actionsBlock, 'UserForm') →
+ * [
+ *   { id: 'UserForm$createUser', name: 'createUser', params: ['data'] },
+ *   { id: 'UserForm$deleteUser', name: 'deleteUser', params: ['id'] }
+ * ]
+ */
+export function extractServerActions(actionsBlock, componentId) {
+  const serverActions = [];
+
+  if (!actionsBlock || !actionsBlock.functions) {
+    return serverActions;
+  }
+
+  for (const action of actionsBlock.functions) {
+    if (isServerAction(action)) {
+      serverActions.push({
+        id: `${componentId}$${action.name}`,
+        name: action.name,
+        params: action.params || []
+      });
+    }
+  }
+
+  return serverActions;
+}
+
+/**
+ * Extract all exported functions from module
+ * @param {Object} ast - Module AST
+ * @returns {Array<{name, params, async}>} Exported functions
+ */
+export function extractExportedFunctions(ast) {
+  const functions = [];
+
+  if (!ast.body) {
+    return functions;
+  }
+
+  for (const node of ast.body) {
+    // export function name() { }
+    if (node.type === 'ExportDeclaration' && node.declaration?.type === 'FunctionDeclaration') {
+      const fn = node.declaration;
+      functions.push({
+        name: fn.name,
+        params: fn.params || [],
+        async: fn.async || false
+      });
+    }
+
+    // export { fn1, fn2 }
+    if (node.type === 'ExportNamedDeclaration' && node.specifiers) {
+      for (const specifier of node.specifiers) {
+        // Need to find the actual function declaration
+        const fnDecl = ast.body.find(n =>
+          n.type === 'FunctionDeclaration' && n.name === specifier.local
+        );
+        if (fnDecl) {
+          functions.push({
+            name: fnDecl.name,
+            params: fnDecl.params || [],
+            async: fnDecl.async || false
+          });
+        }
+      }
+    }
+  }
+
+  return functions;
+}
+
+// ============================================================
+// Server-Side Registration
+// ============================================================
+
+/**
+ * Generate server-side registration code
+ * @param {Array<{id, name}>} serverActions - Server Actions metadata
+ * @param {string} moduleId - Module identifier
+ * @returns {string} Registration code
+ *
+ * @example
+ * // generateServerRegistration([{ id: 'UserForm$createUser', name: 'createUser' }], 'UserForm')
+ * // →
+ * import { registerServerAction } from 'pulse-js-framework/runtime/server-components';
+ * import { createUser } from './UserForm.server.js';
+ * registerServerAction('UserForm$createUser', createUser);
+ */
+export function generateServerRegistration(serverActions, moduleId) {
+  if (!serverActions || serverActions.length === 0) {
+    return '';
+  }
+
+  const imports = `import { registerServerAction } from 'pulse-js-framework/runtime/server-components';`;
+  const moduleImport = `import { ${serverActions.map(a => a.name).join(', ')} } from './${moduleId}.server.js';`;
+
+  const registrations = serverActions.map(action =>
+    `registerServerAction('${action.id}', ${action.name});`
+  );
+
+  return [imports, moduleImport, '', ...registrations].join('\n');
+}
+
+// ============================================================
+// Validation
+// ============================================================
+
+/**
+ * Validate Server Action function
+ * @param {Object} functionNode - Function AST node
+ * @returns {{valid: boolean, errors: Array<string>}} Validation result
+ *
+ * @example
+ * validateServerAction(functionNode)
+ * // → { valid: false, errors: ['Server Action must be async'] }
+ */
+export function validateServerAction(functionNode) {
+  const errors = [];
+
+  // Must be async
+  if (!functionNode.async) {
+    errors.push('Server Action must be async');
+  }
+
+  // Parameters must be serializable (no functions, classes)
+  if (functionNode.params) {
+    for (const param of functionNode.params) {
+      // Check for destructuring with functions (hard to validate at compile time)
+      // This is a basic check; runtime will validate actual arguments
+      if (param.type === 'FunctionExpression' || param.type === 'ArrowFunctionExpression') {
+        errors.push(`Server Action parameter '${param.name || 'anonymous'}' cannot be a function`);
+      }
+    }
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors
+  };
+}
+
+/**
+ * Validate all Server Actions in module
+ * @param {Array<Object>} actions - Server Action nodes
+ * @returns {{valid: boolean, errors: Array<{action: string, errors: Array<string>}>}} Validation result
+ */
+export function validateServerActions(actions) {
+  const allErrors = [];
+
+  for (const action of actions) {
+    const result = validateServerAction(action);
+    if (!result.valid) {
+      allErrors.push({
+        action: action.name,
+        errors: result.errors
+      });
+    }
+  }
+
+  return {
+    valid: allErrors.length === 0,
+    errors: allErrors
+  };
+}
+
+// ============================================================
+// Exports
+// ============================================================
+
+export default {
+  isServerAction,
+  hasServerDirective,
+  transformServerAction,
+  transformServerModule,
+  extractServerActions,
+  extractExportedFunctions,
+  generateServerRegistration,
+  validateServerAction,
+  validateServerActions
+};

package/compiler/transformer/export.js

@@ -13,6 +13,7 @@ export function generateExport(transformer) {
   const pageName = transformer.ast.page?.name || 'Component';
   const routePath = transformer.ast.route?.path || null;
   const hasInit = transformer.actionNames.has('init');
+  const directive = transformer.directive;
 
   const lines = ['// Export'];
   lines.push(`export const ${pageName} = {`);
@@ -22,6 +23,12 @@ export function generateExport(transformer) {
     lines.push(`  route: ${JSON.stringify(routePath)},`);
   }
 
+  // Add Server Component directive metadata
+  if (directive) {
+    lines.push(`  __directive: ${JSON.stringify(directive)},  // 'use client' or 'use server'`);
+    lines.push(`  __componentId: ${JSON.stringify(pageName)},`);
+  }
+
   // Mount with reactive re-rendering (preserves focus)
   lines.push('  mount: (target) => {');
   lines.push('    const container = typeof target === "string" ? document.querySelector(target) : target;');

package/compiler/transformer/expressions.js

@@ -191,39 +191,83 @@ export function transformExpressionString(transformer, exprStr) {
   // invalid code like stateVar.get() = expr (LHS of assignment is not a reference)
   for (const stateVar of transformer.stateVars) {
     // Compound assignment: stateVar += expr -> stateVar.update(_v => _v + expr)
-    result = result.replace(
-      new RegExp(`\\b${stateVar}\\s*(\\+=|-=|\\*=|\\/=|&&=|\\|\\|=|\\?\\?=)\\s*`, 'g'),
-      (_match, op) => {
-        const baseOp = op.slice(0, -1); // Remove trailing '='
-        return `${stateVar}.update(_v => _v ${baseOp} `;
+    // Use bracket-balancing to find the end of the RHS expression
+    const compoundPattern = new RegExp(`\\b${stateVar}\\s*(\\+=|-=|\\*=|\\/=|&&=|\\|\\|=|\\?\\?=)\\s*`, 'g');
+    let compoundMatch;
+    const compoundReplacements = [];
+
+    while ((compoundMatch = compoundPattern.exec(result)) !== null) {
+      const op = compoundMatch[1];
+      const baseOp = op.slice(0, -1);
+      const rhsStart = compoundMatch.index + compoundMatch[0].length;
+
+      // Find end of RHS expression using bracket balancing
+      let depth = 0;
+      let endIdx = rhsStart;
+      for (let i = rhsStart; i < result.length; i++) {
+        const ch = result[i];
+        if (ch === '(' || ch === '[' || ch === '{') { depth++; endIdx = i + 1; continue; }
+        if (ch === ')' || ch === ']' || ch === '}') {
+          if (depth > 0) { depth--; endIdx = i + 1; continue; }
+          break; // closing bracket at depth 0 = boundary
+        }
+        if (depth === 0 && (ch === ';' || ch === ',')) break;
+        endIdx = i + 1;
       }
-    );
-    // Close the .update() call - find the end of the expression after the replacement
-    // This is handled by the fact that the expression continues after the replacement text
-    // and the closing paren is added by wrapping logic below.
+
+      const rhs = result.slice(rhsStart, endIdx).trim();
+      if (rhs) {
+        compoundReplacements.push({
+          start: compoundMatch.index,
+          end: endIdx,
+          replacement: `${stateVar}.update(_v => _v ${baseOp} ${rhs})`
+        });
+      }
+    }
+
+    // Apply compound replacements in reverse order
+    for (let i = compoundReplacements.length - 1; i >= 0; i--) {
+      const r = compoundReplacements[i];
+      result = result.slice(0, r.start) + r.replacement + result.slice(r.end);
+    }
 
     // Simple assignment: stateVar = expr -> stateVar.set(expr)
-    // Use negative lookbehind to skip compound assignments (already handled)
-    // Use negative lookahead to skip == and ===
-    result = result.replace(
-      new RegExp(`\\b${stateVar}\\s*=(?!=)`, 'g'),
-      `${stateVar}.set(`
-    );
-  }
+    // Use bracket-balancing to find the end of the RHS expression
+    const simplePattern = new RegExp(`\\b${stateVar}\\s*=(?!=)\\s*`, 'g');
+    let simpleMatch;
+    const simpleReplacements = [];
 
-  // If we inserted .set( or .update(, we need to close the parenthesis
-  // Find unclosed .set( and .update( calls and close them at end of expression
-  if (result.includes('.set(') || result.includes('.update(_v =>')) {
-    // For .update(_v => _v op expr), close with )
-    result = result.replace(
-      /\.update\(_v => _v [^\)]*$/,
-      (m) => m + ')'
-    );
-    // For .set(expr), close with )
-    result = result.replace(
-      /\.set\(([^)]*$)/,
-      (_m, expr) => `.set(${expr})`
-    );
+    while ((simpleMatch = simplePattern.exec(result)) !== null) {
+      const rhsStart = simpleMatch.index + simpleMatch[0].length;
+
+      let depth = 0;
+      let endIdx = rhsStart;
+      for (let i = rhsStart; i < result.length; i++) {
+        const ch = result[i];
+        if (ch === '(' || ch === '[' || ch === '{') { depth++; endIdx = i + 1; continue; }
+        if (ch === ')' || ch === ']' || ch === '}') {
+          if (depth > 0) { depth--; endIdx = i + 1; continue; }
+          break;
+        }
+        if (depth === 0 && (ch === ';' || ch === ',')) break;
+        endIdx = i + 1;
+      }
+
+      const rhs = result.slice(rhsStart, endIdx).trim();
+      if (rhs) {
+        simpleReplacements.push({
+          start: simpleMatch.index,
+          end: endIdx,
+          replacement: `${stateVar}.set(${rhs})`
+        });
+      }
+    }
+
+    // Apply simple replacements in reverse order
+    for (let i = simpleReplacements.length - 1; i >= 0; i--) {
+      const r = simpleReplacements[i];
+      result = result.slice(0, r.start) + r.replacement + result.slice(r.end);
+    }
   }
 
   // Transform state var reads (not already transformed to .get/.set/.update)
@@ -238,13 +282,16 @@ export function transformExpressionString(transformer, exprStr) {
   // Add optional chaining when followed by property access for nullable props
   // Props commonly receive null values (e.g., notification: null)
   for (const propVar of transformer.propVars) {
+    // Property access: propVar.x -> propVar.get()?.x
+    // Guard against already-transformed: skip if followed by .get( or .set(
     result = result.replace(
-      new RegExp(`\\b${propVar}\\b(?=\\.)`, 'g'),
+      new RegExp(`\\b${propVar}\\b(?=\\.(?!get\\(|set\\())`, 'g'),
       `${propVar}.get()?`
     );
     // Handle standalone prop var (not followed by property access)
+    // Guard: skip if already followed by .get or .set
     result = result.replace(
-      new RegExp(`\\b${propVar}\\b(?!\\.)`, 'g'),
+      new RegExp(`\\b${propVar}\\b(?!\\.(?:get|set)\\()(?!\\.)`, 'g'),
       `${propVar}.get()`
     );
   }
@@ -414,7 +461,6 @@ export function transformFunctionBody(transformer, tokens) {
 
       for (let i = exprStart; i < code.length; i++) {
         const ch = code[i];
-        const prevCh = i > 0 ? code[i-1] : '';
 
         // Handle string literals
         if (!inString && (ch === '"' || ch === "'" || ch === '`')) {
@@ -424,7 +470,13 @@ export function transformFunctionBody(transformer, tokens) {
           continue;
         }
         if (inString) {
-          if (ch === stringChar && prevCh !== '\\') {
+          if (ch === '\\') {
+            // Skip next character (escaped)
+            i++;
+            endIdx = i + 1;
+            continue;
+          }
+          if (ch === stringChar) {
             inString = false;
           }
           endIdx = i + 1;

package/compiler/transformer/imports.js

@@ -99,6 +99,9 @@ export function generateImports(transformer) {
       }
       if (namespaceSpec) {
         importStr += `* as ${namespaceSpec.local}`;
+        if (namedSpecs.length > 0) {
+          importStr += ', ';
+        }
       }
       if (namedSpecs.length > 0) {
         const named = namedSpecs.map(s =>

package/compiler/transformer/index.js

@@ -53,6 +53,8 @@ export class Transformer {
     this.actionNames = new Set();
     this.importedComponents = new Map();
     this.scopeId = this.options.scopeStyles ? generateScopeId() : null;
+    this.directive = this.ast.directive || null;  // 'use client' | 'use server' | null
+    this.componentId = this.ast.page?.name || 'Component';
 
     // Track a11y feature usage for conditional imports
     this.usesA11y = {

package/compiler/transformer/store.js

@@ -53,7 +53,7 @@ export function transformStore(transformer, storeBlock, transformValue) {
     lines.push(stateProps);
     lines.push('}, {');
     lines.push(`  persist: ${storeBlock.persist},`);
-    lines.push(`  storageKey: '${storeBlock.storageKey}'`);
+    lines.push(`  storageKey: ${JSON.stringify(storeBlock.storageKey)}`);
     lines.push('});');
     lines.push('');
   }

package/compiler/transformer/style.js

@@ -213,11 +213,12 @@ export function flattenStyleRule(transformer, rule, parentSelector, output, atRu
     // Conditional group @-rules (@media, @supports, @container) wrap their nested rules
     // They can be nested inside each other
     if (isConditionalGroup) {
-      // Combine with existing wrapper if present
-      const combinedWrapper = atRuleWrapper ? `${atRuleWrapper} { ${selector}` : selector;
+      // For nested conditional groups, build a properly structured wrapper array
+      // so closing braces are correctly generated
+      const wrappers = atRuleWrapper ? [atRuleWrapper, selector] : [selector];
 
       for (const nested of rule.nestedRules) {
-        flattenStyleRule(transformer, nested, parentSelector, output, combinedWrapper, false);
+        flattenStyleRule(transformer, nested, parentSelector, output, wrappers, false);
       }
       return;
     }
@@ -253,15 +254,23 @@ export function flattenStyleRule(transformer, rule, parentSelector, output, atRu
   if (rule.properties.length > 0) {
     const lines = [];
 
-    // If wrapped in an @-rule, output the wrapper
+    // If wrapped in an @-rule, output the wrapper(s)
     if (atRuleWrapper) {
-      lines.push(`  ${atRuleWrapper} {`);
-      lines.push(`    ${scopedSelector} {`);
+      const wrappers = Array.isArray(atRuleWrapper) ? atRuleWrapper : [atRuleWrapper];
+      const baseIndent = '  ';
+      for (let w = 0; w < wrappers.length; w++) {
+        lines.push(`${baseIndent}${'  '.repeat(w)}${wrappers[w]} {`);
+      }
+      const contentIndent = baseIndent + '  '.repeat(wrappers.length);
+      lines.push(`${contentIndent}${scopedSelector} {`);
       for (const prop of rule.properties) {
-        lines.push(`      ${prop.name}: ${prop.value};`);
+        lines.push(`${contentIndent}  ${prop.name}: ${prop.value};`);
+      }
+      lines.push(`${contentIndent}}`);
+      // Close wrappers in reverse order
+      for (let w = wrappers.length - 1; w >= 0; w--) {
+        lines.push(`${baseIndent}${'  '.repeat(w)}}`);
       }
-      lines.push('    }');
-      lines.push('  }');
     } else {
       lines.push(`  ${scopedSelector} {`);
       for (const prop of rule.properties) {
@@ -380,12 +389,32 @@ export function scopeStyleSelector(transformer, selector) {
  */
 function scopePseudoClassSelector(transformer, selector) {
   // Match functional pseudo-classes: :has(), :is(), :where(), :not()
-  return selector.replace(
-    /:(has|is|where|not)\(([^)]+)\)/g,
-    (_match, pseudoClass, inner) => {
-      // Recursively scope the inner selector
-      const scopedInner = scopeStyleSelector(transformer, inner);
-      return `:${pseudoClass}(${scopedInner})`;
+  // Use balanced parenthesis matching to handle nested pseudo-classes like :not(:hover)
+  const pattern = /:(has|is|where|not)\(/g;
+  let result = '';
+  let lastIndex = 0;
+  let match;
+
+  while ((match = pattern.exec(selector)) !== null) {
+    result += selector.slice(lastIndex, match.index);
+    const pseudoClass = match[1];
+    const innerStart = match.index + match[0].length;
+
+    // Find matching closing paren with depth tracking
+    let depth = 1;
+    let i = innerStart;
+    for (; i < selector.length && depth > 0; i++) {
+      if (selector[i] === '(') depth++;
+      else if (selector[i] === ')') depth--;
     }
-  );
+
+    const inner = selector.slice(innerStart, i - 1);
+    const scopedInner = scopeStyleSelector(transformer, inner);
+    result += `:${pseudoClass}(${scopedInner})`;
+    lastIndex = i;
+    pattern.lastIndex = i;
+  }
+
+  result += selector.slice(lastIndex);
+  return result;
 }

package/compiler/transformer/view.js

@@ -557,6 +557,9 @@ export function transformElement(transformer, node, indent) {
     for (const child of node.children) {
       content.push(transformViewNode(transformer, child, 0).trim());
     }
+    if (content.length === 0) {
+      return `${pad}srOnly('')`;
+    }
     const contentCode = content.length === 1 ? content[0] : `[${content.join(', ')}]`;
     return `${pad}srOnly(${contentCode})`;
   }
@@ -669,7 +672,24 @@ export function transformElement(transformer, node, indent) {
     if (attr.isInterpolated) {
       // String with interpolation: "display: {show ? 'block' : 'none'}"
       // Convert to template literal: `display: ${show.get() ? 'block' : 'none'}`
-      const templateStr = attr.expr.replace(/\{/g, '${');
+      // Only convert top-level interpolation braces, not nested braces (e.g., object literals)
+      let templateStr = '';
+      let depth = 0;
+      for (let ci = 0; ci < attr.expr.length; ci++) {
+        const ch = attr.expr[ci];
+        if (ch === '{' && depth === 0) {
+          templateStr += '${';
+          depth = 1;
+        } else if (ch === '{' && depth > 0) {
+          templateStr += ch;
+          depth++;
+        } else if (ch === '}' && depth > 0) {
+          depth--;
+          templateStr += ch;
+        } else {
+          templateStr += ch;
+        }
+      }
       exprCode = '`' + transformExpressionString(transformer, templateStr) + '`';
     } else {
       // Pure expression: {searchQuery}
@@ -688,6 +708,7 @@ export function transformElement(transformer, node, indent) {
  * @returns {string} Scoped selector
  */
 export function addScopeToSelector(transformer, selector) {
+  if (!selector) return `.${transformer.scopeId}`;
   // If selector has classes, add scope class after the first class
   // Otherwise add it at the end
   if (selector.includes('.')) {
@@ -821,7 +842,7 @@ function expressionUsesState(transformer, node) {
 export function transformComponentCall(transformer, node, indent) {
   const pad = ' '.repeat(indent);
   const selectorParts = node.selector.match(/^([a-zA-Z][a-zA-Z0-9]*)/);
-  const componentName = selectorParts[1];
+  const componentName = selectorParts ? selectorParts[1] : node.selector;
 
   // Extract slots from children
   const slots = {};