feat: add VaultLoader for reusable Nunjucks templates in TEMPLATE renderer

.changeset/nunjucks-template-renderer.md

@@ -0,0 +1,12 @@
+---
+"sqlseal": minor
+---
+
+Replace Handlebars with Nunjucks in TEMPLATE renderer
+
+Swap the template engine from Handlebars to Nunjucks for richer template capabilities.
+Nunjucks provides native groupby/unique filters, macros, template inheritance,
+set/variables, and include/import directives without SQL workarounds.
+
+Breaking change: existing templates using Handlebars syntax ({{#each}}, {{#if}}, {{#unless}})
+must be updated to Nunjucks equivalents ({% for %}, {% if %}, {% set %}).

.changeset/vault-template-loader.md

@@ -0,0 +1,11 @@
+---
+"sqlseal": minor
+---
+
+Add VaultLoader for reusable Nunjucks templates in TEMPLATE renderer
+
+The TEMPLATE renderer now supports `{% include %}` and `{% from ... import %}` directives
+to load `.njk` template files from the Obsidian vault. This enables users to define reusable
+templates and macros once and reference them across multiple code blocks.
+
+Templates are cached at startup and kept in sync via vault file watchers.

jest.config.js

@@ -2,7 +2,10 @@
 module.exports = {
   testEnvironment: "node",
   transform: {
-    "^.+.tsx?$": ["ts-jest",{}],
-    "^.+.ts?$": ["ts-jest",{}],
+    "^.+.tsx?$": ["ts-jest", { tsconfig: { esModuleInterop: true } }],
+    "^.+.ts?$": ["ts-jest", { tsconfig: { esModuleInterop: true } }],
+  },
+  moduleNameMapper: {
+    "^obsidian$": "<rootDir>/src/__mocks__/obsidian.ts",
   },
 };

package.json

@@ -67,7 +67,7 @@
     "esbuild-plugin-polyfill-node": "^0.3.0",
     "esprima": "^4.0.1",
     "estraverse": "^5.3.0",
-    "handlebars": "^4.7.8",
+    "nunjucks": "^3.2.4",
     "json5": "^2.2.3",
     "jsonpath": "^1.1.1",
     "lodash": "^4.17.21",

src/__mocks__/obsidian.ts

@@ -0,0 +1,8 @@
+export class App {}
+export class Plugin {}
+export class TAbstractFile {
+	path = "";
+}
+export class TFile extends TAbstractFile {
+	extension = "";
+}

src/modules/editor/init.ts

@@ -7,6 +7,7 @@ import { GridRenderer } from "./renderer/GridRenderer";
 import { ListRenderer } from "./renderer/ListRenderer";
 import { TemplateRenderer } from "./renderer/TemplateRenderer";
 import { MarkdownRenderer } from "./renderer/MarkdownRenderer";
+import { VaultLoader } from "./renderer/VaultLoader";
 import { Settings } from "../settings/Settings";
 import { SqlSealInlineHandler } from "./codeblockHandler/inline/InlineCodeHandler";
 import { SqlSealCodeblockHandler } from "./codeblockHandler/SqlSealCodeblockHandler";
@@ -56,6 +57,8 @@ export const editorInit = (
 		);
 	};
 
+	const vaultLoader = new VaultLoader(app, plugin);
+
 	const registerViews = () => {
 		rendererRegistry.register(
 			"sql-seal-internal-table",
@@ -72,14 +75,16 @@ export const editorInit = (
 		rendererRegistry.register("sql-seal-internal-list", new ListRenderer(app));
 		rendererRegistry.register(
 			"sql-seal-internal-template",
-			new TemplateRenderer(app),
+			new TemplateRenderer(app, vaultLoader),
 		);
 	};
 
 	return () => {
 		registerViews();
 
 		app.workspace.onLayoutReady(async () => {
+			await vaultLoader.loadAll();
+			vaultLoader.registerWatchers();
 			registerInlineCodeblocks();
 			registerBlockCodeblock();
 		});

src/modules/editor/parser.ts

@@ -51,7 +51,7 @@ export const SQLSealLangDefinition = (views: ViewDefinition[], flags: readonly F
             ViewExpression =           ${viewsDefinitions}
             ExtraFlags =               ${flagsDefinitions}
             anyObject =                "{"  (~selectKeyword any)*
-            handlebarsTemplate =       (~selectKeyword any)*
+            nunjucksTemplate =       (~selectKeyword any)*
             javascriptTemplate =       (~selectKeyword any)*
             selectKeyword =            caseInsensitive<"WITH"> | caseInsensitive<"SELECT">
             tableKeyword =             caseInsensitive<"TABLE">

src/modules/editor/renderer/TemplateRenderer.ts

@@ -1,60 +1,103 @@
-// This is renderer for a very basic List view.
 import { App } from "obsidian";
 import { RendererConfig, RendererContext } from "./rendererRegistry";
 import { displayError } from "../../../utils/ui";
-import Handlebars from "handlebars";
+import nunjucks from "nunjucks";
 import { ViewDefinition } from "../parser";
 import { ParseResults } from "../../syntaxHighlight/cellParser/parseResults";
+import { VaultLoader } from "./VaultLoader";
+
+function registerFilters(env: nunjucks.Environment): void {
+    // Register custom filters
+    env.addFilter("groupby", (arr: any[], key: string) => {
+        const groups: Record<string, any[]> = {};
+        for (const item of arr) {
+            const groupKey = String(item[key] ?? "");
+            groups[groupKey] ??= [];
+            groups[groupKey].push(item);
+        }
+        return Object.entries(groups).map(([k, items]) => ({
+            grouper: k,
+            list: items,
+        }));
+    });
+
+    env.addFilter("unique", (arr: any[], key?: string) => {
+        if (!key) return [...new Set(arr)];
+        const seen = new Set<string>();
+        return arr.filter((item) => {
+            const val = String(item[key] ?? "");
+            if (seen.has(val)) return false;
+            seen.add(val);
+            return true;
+        });
+    });
+}
 
 interface TemplateRendererConfig {
-    template: HandlebarsTemplateDelegate
+    template: nunjucks.Template;
 }
 
 export class TemplateRenderer implements RendererConfig {
-    constructor(private readonly app: App) {
+    private readonly env: nunjucks.Environment;
+
+    constructor(
+        private readonly app: App,
+        loader?: VaultLoader,
+    ) {
+        this.env = new nunjucks.Environment(
+            loader ?? null,
+            { autoescape: false },
+        );
+        registerFilters(this.env);
     }
 
     get rendererKey() {
-        return 'template'
+        return "template";
     }
 
     get viewDefinition(): ViewDefinition {
         return {
             name: this.rendererKey,
-            argument: 'handlebarsTemplate?',
-            singleLine: false
-        }
+            argument: "nunjucksTemplate?",
+            singleLine: false,
+        };
     }
 
     validateConfig(config: string): TemplateRendererConfig {
         if (!config) {
             return {
-                template: Handlebars.compile('No template Provided')
-            }
+                template: nunjucks.compile("No template provided", this.env),
+            };
         }
         return {
-            template: Handlebars.compile(config)
-        }
+            template: nunjucks.compile(config, this.env),
+        };
     }
 
-    render(config: TemplateRendererConfig, el: HTMLElement, { cellParser }: RendererContext) {
+    render(
+        config: TemplateRendererConfig,
+        el: HTMLElement,
+        { cellParser }: RendererContext,
+    ) {
         return {
             render: ({ columns, data, frontmatter }: any) => {
-                el.empty()
-
-                const parser = new ParseResults(cellParser!, (el) => new Handlebars.SafeString(el.outerHTML))
+                el.empty();
+
+                const parser = new ParseResults(
+                    cellParser!,
+                    (el) => new nunjucks.runtime.SafeString(el.outerHTML),
+                );
 
-                // Seems to be the only way to render handlebars into DOM. Don't like it but what can we do.
-                el.innerHTML = config.template({
+                el.innerHTML = config.template.render({
                     data: parser.parse(data, columns),
                     columns,
-                    properties: frontmatter
-                })
-                parser.initialise(el)
+                    properties: frontmatter,
+                });
+                parser.initialise(el);
             },
             error: (error: string) => {
-                displayError(el, error)
-            }
-        }
+                displayError(el, error);
+            },
+        };
     }
-}
+}

src/modules/editor/renderer/VaultLoader.ts

@@ -0,0 +1,93 @@
+import { App, Plugin, TFile } from "obsidian";
+
+const TEMPLATE_EXTENSION = "njk";
+
+interface LoaderSource {
+	src: string;
+	path: string;
+	noCache: boolean;
+}
+
+export class VaultLoader {
+	private _templates: Map<string, string> = new Map();
+
+	constructor(
+		private readonly app: App,
+		private readonly plugin: Plugin,
+	) {}
+
+	getSource(name: string): LoaderSource {
+		let src = this._templates.get(name);
+
+		if (src === undefined && !name.includes(".")) {
+			src = this._templates.get(name + "." + TEMPLATE_EXTENSION);
+		}
+
+		if (src === undefined) {
+			throw new Error(`Template not found: ${name}`);
+		}
+
+		return { src, path: name, noCache: true };
+	}
+
+	async loadAll(): Promise<void> {
+		const files = this.app.vault
+			.getFiles()
+			.filter((f) => f.extension === TEMPLATE_EXTENSION);
+
+		for (const file of files) {
+			const content = await this.app.vault.cachedRead(file);
+			this._templates.set(file.path, content);
+		}
+	}
+
+	registerWatchers(): void {
+		this.plugin.registerEvent(
+			this.app.vault.on("modify", async (file) => {
+				if (
+					file instanceof TFile &&
+					file.extension === TEMPLATE_EXTENSION
+				) {
+					const content = await this.app.vault.cachedRead(file);
+					this._templates.set(file.path, content);
+				}
+			}),
+		);
+
+		this.plugin.registerEvent(
+			this.app.vault.on("delete", (file) => {
+				if (
+					file instanceof TFile &&
+					file.extension === TEMPLATE_EXTENSION
+				) {
+					this._templates.delete(file.path);
+				}
+			}),
+		);
+
+		this.plugin.registerEvent(
+			this.app.vault.on("rename", async (file, oldPath) => {
+				if (file instanceof TFile) {
+					this._templates.delete(oldPath);
+					if (file.extension === TEMPLATE_EXTENSION) {
+						const content =
+							await this.app.vault.cachedRead(file);
+						this._templates.set(file.path, content);
+					}
+				}
+			}),
+		);
+
+		this.plugin.registerEvent(
+			this.app.vault.on("create", async (file) => {
+				if (
+					file instanceof TFile &&
+					file.extension === TEMPLATE_EXTENSION
+				) {
+					const content = await this.app.vault.cachedRead(file);
+					this._templates.set(file.path, content);
+				}
+			}),
+		);
+	}
+}