@lark.js/mvc 0.0.6 → 0.0.8

package/dist/compiler.d.cts

@@ -0,0 +1,76 @@
+/** Options for compileTemplate() */
+interface CompileOptions {
+    /** Enable debug mode with line tracking (default: false) */
+    debug?: boolean;
+    /** Global variable names to destructure from $$ (refData) */
+    globalVars?: string[];
+    /** File path for debug error messages (default: undefined) */
+    file?: string;
+}
+
+/**
+ * @lark.js/mvc Template Compiler
+ *
+ *   convertArtSyntax()    ({{}} → <% %>)
+ *   processViewEvents()      (@event prefix + param encoding)
+ *   compileToFunction()  (<% %> → JS template function)
+ *   extractGlobalVars()   (AST-based global var analysis via @babel/parser)
+ *
+ * - All template operators: = (escape), ! (raw), @ (ref lookup), : (binding)
+ * - @event attribute processing with $splitter prefix + \x1e separator
+ * - $strSafe (null-safe toString), $encHtml (HTML entity encode), $encUri (URI encode), $encQuote (quote encode), $refFn (ref lookup)
+ * - Debug mode with line tracking ($dbgExpr/$dbgArt/$dbgLine) and try-catch error wrapper
+ * - View ID injection (\x1f → '+$viewId+')
+ * - Post-processing cleanup of empty concatenations
+ * - 0 configuration: auto-extract variables via AST analysis
+ *
+ * Template syntax:
+ *   {{=variable}}              → escaped output
+ *   {{:variable}}              → two-way binding (same as = for rendering)
+ *   {{!variable}}              → raw output (no HTML escaping)
+ *   {{@variable}}              → reference lookup for component data passing
+ *   {{forOf list as item}}      → loop
+ *   {{forOf list as item idx}}  → loop with index
+ *   {{forIn obj as val key}}   → object iteration
+ *   {{for(let i=0;i<n;i++)}}  → generic for loop
+ *   {{if condition}}           → conditional
+ *   {{else if condition}}      → else-if
+ *   {{else}}                   → else
+ *   {{/if}} / {{/forOf}} / {{/forIn}} / {{/for}} → close blocks
+ *   {{set a = b}}              → variable declaration
+ */
+
+/**
+ * Compile an HTML template string into a JS module string.
+ * This is the main entry point for both Vite and Webpack loaders.
+ *
+ * The output is an ES module that exports a function with the signature:
+ *   (data, viewId, refData) => string
+ *
+ * Internally it calls the compiled template function with the standard
+ * signature: ($data,$viewId,$refAlt,$encHtml,$strSafe,$encUri,$refFn,$encQuote)
+ *
+ * @param source - The raw HTML template content
+ * @param options - Compilation options
+ * @returns ES module source code exporting the compiled template function
+ */
+declare function compileTemplate(source: string, options?: CompileOptions): string;
+/**
+ * Extract global variable names from a template source using AST analysis.
+ *
+ * 1. Convert template commands (<% %> blocks) into a form parseable by an AST parser
+ * 2. Walk the AST to find all Identifier nodes
+ * 3. Track variable declarations (VariableDeclarator, FunctionDeclaration) as local vars
+ * 4. Track function parameters as local vars
+ * 5. Remaining identifiers that are not local and not in the exclusion list are "global" —
+ *    they must be passed in as part of the data context ($$)
+ *
+ * This replaces the old regex-based `extractVariables()` with proper scope analysis,
+ * eliminating false positives from local template variables and function parameters.
+ *
+ * @param source - The raw HTML template content (with {{ }} syntax)
+ * @returns Array of global variable names found in the template
+ */
+declare function extractGlobalVars(source: string): string[];
+
+export { compileTemplate, extractGlobalVars };

package/dist/compiler.d.ts

@@ -0,0 +1,76 @@
+/** Options for compileTemplate() */
+interface CompileOptions {
+    /** Enable debug mode with line tracking (default: false) */
+    debug?: boolean;
+    /** Global variable names to destructure from $$ (refData) */
+    globalVars?: string[];
+    /** File path for debug error messages (default: undefined) */
+    file?: string;
+}
+
+/**
+ * @lark.js/mvc Template Compiler
+ *
+ *   convertArtSyntax()    ({{}} → <% %>)
+ *   processViewEvents()      (@event prefix + param encoding)
+ *   compileToFunction()  (<% %> → JS template function)
+ *   extractGlobalVars()   (AST-based global var analysis via @babel/parser)
+ *
+ * - All template operators: = (escape), ! (raw), @ (ref lookup), : (binding)
+ * - @event attribute processing with $splitter prefix + \x1e separator
+ * - $strSafe (null-safe toString), $encHtml (HTML entity encode), $encUri (URI encode), $encQuote (quote encode), $refFn (ref lookup)
+ * - Debug mode with line tracking ($dbgExpr/$dbgArt/$dbgLine) and try-catch error wrapper
+ * - View ID injection (\x1f → '+$viewId+')
+ * - Post-processing cleanup of empty concatenations
+ * - 0 configuration: auto-extract variables via AST analysis
+ *
+ * Template syntax:
+ *   {{=variable}}              → escaped output
+ *   {{:variable}}              → two-way binding (same as = for rendering)
+ *   {{!variable}}              → raw output (no HTML escaping)
+ *   {{@variable}}              → reference lookup for component data passing
+ *   {{forOf list as item}}      → loop
+ *   {{forOf list as item idx}}  → loop with index
+ *   {{forIn obj as val key}}   → object iteration
+ *   {{for(let i=0;i<n;i++)}}  → generic for loop
+ *   {{if condition}}           → conditional
+ *   {{else if condition}}      → else-if
+ *   {{else}}                   → else
+ *   {{/if}} / {{/forOf}} / {{/forIn}} / {{/for}} → close blocks
+ *   {{set a = b}}              → variable declaration
+ */
+
+/**
+ * Compile an HTML template string into a JS module string.
+ * This is the main entry point for both Vite and Webpack loaders.
+ *
+ * The output is an ES module that exports a function with the signature:
+ *   (data, viewId, refData) => string
+ *
+ * Internally it calls the compiled template function with the standard
+ * signature: ($data,$viewId,$refAlt,$encHtml,$strSafe,$encUri,$refFn,$encQuote)
+ *
+ * @param source - The raw HTML template content
+ * @param options - Compilation options
+ * @returns ES module source code exporting the compiled template function
+ */
+declare function compileTemplate(source: string, options?: CompileOptions): string;
+/**
+ * Extract global variable names from a template source using AST analysis.
+ *
+ * 1. Convert template commands (<% %> blocks) into a form parseable by an AST parser
+ * 2. Walk the AST to find all Identifier nodes
+ * 3. Track variable declarations (VariableDeclarator, FunctionDeclaration) as local vars
+ * 4. Track function parameters as local vars
+ * 5. Remaining identifiers that are not local and not in the exclusion list are "global" —
+ *    they must be passed in as part of the data context ($$)
+ *
+ * This replaces the old regex-based `extractVariables()` with proper scope analysis,
+ * eliminating false positives from local template variables and function parameters.
+ *
+ * @param source - The raw HTML template content (with {{ }} syntax)
+ * @returns Array of global variable names found in the template
+ */
+declare function extractGlobalVars(source: string): string[];
+
+export { compileTemplate, extractGlobalVars };