Merge pull request #1122 from chhoumann/1121-feature-request-allow-creating-and-templating-base-base-files

feat: support .base templates and guard capture targets

Author: chhoumann

docs/docs/Choices/CaptureChoice.md

@@ -16,6 +16,11 @@ Allows to quickly capture your input and save it from anywhere in Obsidian, with
 _Capture To_ is the name of the file you are capturing to.
 You can choose to either enable _Capture to active file_, or you can enter a file name in the _File Name_ input field.
 
+QuickAdd treats file names as basename-first by default:
+- If you do **not** provide an extension, QuickAdd creates/targets a Markdown file (`.md`).
+- If you provide an explicit supported extension (for example `.md` or `.canvas`), QuickAdd keeps that extension.
+- Capture to `.base` files is not supported. Use a Template choice for `.base` workflows.
+
 This field also supports the [format syntax](/FormatSyntax.md), which allows you to use dynamic file names.
 I have one for my daily journal with the name `bins/daily/{{DATE:gggg-MM-DD - ddd MMM D}}.md`.
 This automatically finds the file for the day, and whatever I enter will be captured to it.
@@ -140,6 +145,8 @@ If you do not enable this, QuickAdd will default to `{{VALUE}}`, which will inse
 
 You can use [format syntax](/FormatSyntax.md) here, which allows you to use dynamic values in your capture format.
 
+If you want to insert `.base` content into your current note, keep **Capture to active file** enabled and use a `.base` template token in the capture format. See [Capture: Insert a Related Notes Base into an MOC Note](/Examples/Capture_InsertBaseTemplateIntoActiveFile.md).
+
 If your capture format includes an inline `js quickadd` block and you need to
 transform user input, prefer reading input in script code through
 `this.quickAddApi.inputPrompt(...)` and/or assigning script variables on

docs/docs/Choices/TemplateChoice.md

@@ -7,7 +7,7 @@ The template choice type is not meant to be a replacement for [Templater](https:
 ## Mandatory
 **Template Path**. This is a path to the template you wish to insert. Paths are vault-relative; a leading `/` is ignored.
 
-QuickAdd supports both markdown (`.md`) and canvas (`.canvas`) templates. When using a canvas template, the created file will also be a canvas file with the same extension.
+QuickAdd supports markdown (`.md`), canvas (`.canvas`), and base (`.base`) templates. The created file uses the same extension as the template.
 
 ## Optional
 **File Name Format**. You can specify a format for the file name, which is based on the format syntax - which you can see further down this page.

docs/docs/Examples/Capture_InsertBaseTemplateIntoActiveFile.md

@@ -0,0 +1,55 @@
+---
+title: "Capture: Insert a Related Notes Base into an MOC Note"
+---
+
+Use this pattern when you want QuickAdd to insert a live "related notes" Base
+view into a map-of-content (MOC) note.
+
+## Why this pattern
+
+Capture does not write directly to `.base` files, but it can still pull content
+from a `.base` template and insert that content into the active markdown note.
+This is useful for MOCs where you want a note-local index of backlinks.
+
+## Setup
+
+1. Create a `.base` template file, for example
+   `Templates/MOC Related Notes.base`:
+
+```yaml
+filters:
+  and:
+    - 'file.ext == "md"'
+    - "file.hasLink(this.file)"
+    - "file.path != this.file.path"
+views:
+  - type: table
+    name: Related notes
+```
+
+2. Create a Capture choice.
+3. Enable **Capture to active file**.
+4. Set **Active file write position** to **Top**.
+5. In **Capture format**, reference your `.base` template with an explicit file
+   extension:
+
+Example:
+
+````markdown
+## Related Notes
+
+```base
+{{TEMPLATE:Templates/MOC Related Notes.base}}
+```
+
+Context: {{VALUE}}
+````
+
+6. Run the Capture choice while your MOC note is active
+   (for example `MOCs/Alpha Project.md`).
+
+QuickAdd resolves the `.base` template and inserts it into the active note.
+Because the base view is embedded in that note, `this.file` points at the MOC,
+so the table shows notes that link to that specific MOC.
+
+![MOC related notes capture demo](../Images/capture_moc_related_notes_demo.png)

docs/docs/Images/capture_moc_related_notes_demo.png

@@ -109,6 +109,7 @@ const sidebars = {
 						"Examples/Capture_AddJournalEntry",
 						"Examples/Capture_AddTaskToKanbanBoard",
 						"Examples/Capture_FetchTasksFromTodoist",
+						"Examples/Capture_InsertBaseTemplateIntoActiveFile",
 					],
 				},
 				{

docs/sidebars.js

@@ -98,9 +98,12 @@ export const LINK_TO_CURRENT_FILE_REGEX = new RegExp(/{{LINKCURRENT}}/i);
 export const FILE_NAME_OF_CURRENT_FILE_REGEX = new RegExp(/{{FILENAMECURRENT}}/i);
 export const MARKDOWN_FILE_EXTENSION_REGEX = new RegExp(/\.md$/);
 export const CANVAS_FILE_EXTENSION_REGEX = new RegExp(/\.canvas$/);
+export const BASE_FILE_EXTENSION_REGEX = new RegExp(/\.base$/);
 export const JAVASCRIPT_FILE_EXTENSION_REGEX = new RegExp(/\.js$/);
 export const MACRO_REGEX = new RegExp(/{{MACRO:([^\n\r}]*)}}/i);
-export const TEMPLATE_REGEX = new RegExp(/{{TEMPLATE:([^\n\r}]*.md)}}/i);
+export const TEMPLATE_REGEX = new RegExp(
+	/{{TEMPLATE:([^\n\r}]*\.(?:md|canvas|base))}}/i,
+);
 export const GLOBAL_VAR_REGEX = new RegExp(/{{GLOBAL_VAR:([^\n\r}]*)}}/i);
 export const INLINE_JAVASCRIPT_REGEX = new RegExp(
 	/`{3,}js quickadd([\s\S]*?)`{3,}/,

src/constants.ts

@@ -4,9 +4,12 @@ import { CaptureChoiceEngine } from "./CaptureChoiceEngine";
 import type ICaptureChoice from "../types/choices/ICaptureChoice";
 import type { IChoiceExecutor } from "../IChoiceExecutor";
 import { isFolder, openFile } from "../utilityObsidian";
+import { QA_INTERNAL_CAPTURE_TARGET_FILE_PATH } from "../constants";
+import { ChoiceAbortError } from "../errors/ChoiceAbortError";
 
-const { setUseSelectionAsCaptureValueMock } = vi.hoisted(() => ({
+const { setUseSelectionAsCaptureValueMock, setTitleMock } = vi.hoisted(() => ({
 	setUseSelectionAsCaptureValueMock: vi.fn(),
+	setTitleMock: vi.fn(),
 }));
 
 vi.mock("../formatters/captureChoiceFormatter", () => ({
@@ -15,7 +18,9 @@ vi.mock("../formatters/captureChoiceFormatter", () => ({
 		setUseSelectionAsCaptureValue(value: boolean) {
 			setUseSelectionAsCaptureValueMock(value);
 		}
-		setTitle() {}
+		setTitle(value: string) {
+			setTitleMock(value);
+		}
 		setDestinationFile() {}
 		setDestinationSourcePath() {}
 		async formatContentOnly(content: string) {
@@ -130,6 +135,7 @@ const createExecutor = (): IChoiceExecutor => ({
 describe("CaptureChoiceEngine selection-as-value resolution", () => {
 	beforeEach(() => {
 		setUseSelectionAsCaptureValueMock.mockClear();
+		setTitleMock.mockClear();
 		vi.mocked(openFile).mockClear();
 	});
 
@@ -214,6 +220,7 @@ describe("CaptureChoiceEngine selection-as-value resolution", () => {
 describe("CaptureChoiceEngine capture target resolution", () => {
 	beforeEach(() => {
 		vi.mocked(isFolder).mockReset();
+		setTitleMock.mockClear();
 	});
 
 	it("treats folder path without trailing slash as folder when folder exists", () => {
@@ -264,4 +271,82 @@ describe("CaptureChoiceEngine capture target resolution", () => {
 
 		expect(result).toEqual({ kind: "file", path: "journals" });
 	});
+
+	it("rejects explicit .base capture target paths", () => {
+		const app = createApp();
+		const engine = new CaptureChoiceEngine(
+			app,
+			{ settings: { useSelectionAsCaptureValue: false } } as any,
+			createChoice({ captureTo: "Boards/Kanban.base" }),
+			createExecutor(),
+		);
+
+		expect(() =>
+			(engine as any).resolveCaptureTarget("Boards/Kanban.base"),
+		).toThrow(ChoiceAbortError);
+	});
+
+	it("rejects preselected .base capture target paths", async () => {
+		const app = createApp();
+		const executor = createExecutor();
+		executor.variables.set(
+			QA_INTERNAL_CAPTURE_TARGET_FILE_PATH,
+			"Boards/Kanban.base",
+		);
+		const engine = new CaptureChoiceEngine(
+			app,
+			{ settings: { useSelectionAsCaptureValue: false } } as any,
+			createChoice(),
+			executor,
+		);
+
+		await expect(
+			(engine as any).getFormattedPathToCaptureTo(false),
+		).rejects.toBeInstanceOf(ChoiceAbortError);
+	});
+
+	it("preserves explicit .canvas capture target paths", async () => {
+		const app = createApp();
+		const engine = new CaptureChoiceEngine(
+			app,
+			{ settings: { useSelectionAsCaptureValue: false } } as any,
+			createChoice({ captureTo: "Boards/Map.canvas" }),
+			createExecutor(),
+		);
+
+		const result = await (engine as any).getFormattedPathToCaptureTo(false);
+
+		expect(result).toBe("Boards/Map.canvas");
+	});
+
+	it("uses extensionless title for created .canvas capture files", async () => {
+		const app = createApp() as any;
+		app.vault.read = vi.fn(async () => "");
+
+		const engine = new CaptureChoiceEngine(
+			app,
+			{ settings: { useSelectionAsCaptureValue: false } } as any,
+			createChoice({
+				createFileIfItDoesntExist: {
+					enabled: true,
+					createWithTemplate: false,
+					template: "",
+				},
+			}),
+			createExecutor(),
+		);
+
+		(engine as any).createFileWithInput = vi.fn(async (path: string) => ({
+			path,
+			basename: path.split("/").pop()?.replace(/\.(base|canvas)$/i, "") ?? "",
+			extension: path.endsWith(".base") ? "base" : "canvas",
+		}));
+
+		await (engine as any).onCreateFileIfItDoesntExist(
+			"Boards/Map.canvas",
+			"capture",
+		);
+
+		expect(setTitleMock).toHaveBeenCalledWith("Map");
+	});
 });

src/engine/CaptureChoiceEngine.selection.test.ts

@@ -4,6 +4,9 @@ import invariant from "src/utils/invariant";
 import merge from "three-way-merge";
 import type { IChoiceExecutor } from "../IChoiceExecutor";
 import {
+	BASE_FILE_EXTENSION_REGEX,
+	CANVAS_FILE_EXTENSION_REGEX,
+	MARKDOWN_FILE_EXTENSION_REGEX,
 	QA_INTERNAL_CAPTURE_TARGET_FILE_PATH,
 	VALUE_SYNTAX,
 } from "../constants";
@@ -30,6 +33,7 @@ import {
 } from "../utilityObsidian";
 import { isCancellationError, reportError } from "../utils/errorUtils";
 import { normalizeFileOpening } from "../utils/fileOpeningDefaults";
+import { basenameWithoutMdOrCanvas } from "../utils/pathUtils";
 import { QuickAddChoiceEngine } from "./QuickAddChoiceEngine";
 import { ChoiceAbortError } from "../errors/ChoiceAbortError";
 import { MacroAbortError } from "../errors/MacroAbortError";
@@ -247,7 +251,7 @@ export class CaptureChoiceEngine extends QuickAddChoiceEngine {
 			typeof preselected === "string" &&
 			preselected.length > 0
 		) {
-			return preselected;
+			return this.normalizeCaptureFilePath(preselected);
 		}
 
 		if (shouldCaptureToActiveFile) {
@@ -264,17 +268,17 @@ export class CaptureChoiceEngine extends QuickAddChoiceEngine {
 		);
 		const resolution = this.resolveCaptureTarget(formattedCaptureTo);
 
-		switch (resolution.kind) {
-			case "vault":
-				return this.selectFileInFolder("", true);
-			case "tag":
-				return this.selectFileWithTag(resolution.tag);
-			case "folder":
-				return this.selectFileInFolder(resolution.folder, false);
-			case "file":
-				return this.normalizeMarkdownFilePath("", resolution.path);
+			switch (resolution.kind) {
+				case "vault":
+					return this.selectFileInFolder("", true);
+				case "tag":
+					return this.selectFileWithTag(resolution.tag);
+				case "folder":
+					return this.selectFileInFolder(resolution.folder, false);
+				case "file":
+					return this.normalizeCaptureFilePath(resolution.path);
+			}
 		}
-	}
 
 	private resolveCaptureTarget(
 		formattedCaptureTo: string,
@@ -287,7 +291,7 @@ export class CaptureChoiceEngine extends QuickAddChoiceEngine {
 		// 1) empty => vault picker
 		// 2) #tag => tag picker
 		// 3) trailing "/" => folder picker (explicit)
-		// 4) ".md" => file
+		// 4) known file extension => file
 		// 5) ambiguous => folder if it exists and no same-name file exists; else file
 		const normalizedCaptureTo = this.stripLeadingSlash(
 			formattedCaptureTo.trim(),
@@ -304,14 +308,23 @@ export class CaptureChoiceEngine extends QuickAddChoiceEngine {
 			};
 		}
 
+		if (BASE_FILE_EXTENSION_REGEX.test(normalizedCaptureTo)) {
+			throw new ChoiceAbortError(
+				`Capture to '.base' files is not supported (${normalizedCaptureTo}). Use a Template choice instead.`,
+			);
+		}
+
 		const endsWithSlash = normalizedCaptureTo.endsWith("/");
 		const folderPath = normalizedCaptureTo.replace(/\/+$/, "");
 
 		if (endsWithSlash) {
 			return { kind: "folder", folder: folderPath };
 		}
 
-		if (normalizedCaptureTo.endsWith(".md")) {
+		if (
+			MARKDOWN_FILE_EXTENSION_REGEX.test(normalizedCaptureTo) ||
+			CANVAS_FILE_EXTENSION_REGEX.test(normalizedCaptureTo)
+		) {
 			return { kind: "file", path: normalizedCaptureTo };
 		}
 
@@ -462,8 +475,8 @@ export class CaptureChoiceEngine extends QuickAddChoiceEngine {
 		newFileContent: string;
 		captureContent: string;
 	}> {
-		// Extract filename without extension from the full path
-		const fileBasename = filePath.split("/").pop()?.replace(/\.md$/, "") || "";
+		// Extract filename without extension from the full path.
+		const fileBasename = basenameWithoutMdOrCanvas(filePath);
 		this.formatter.setTitle(fileBasename);
 
 		// Set the destination path so formatters can generate proper relative links
@@ -549,7 +562,24 @@ export class CaptureChoiceEngine extends QuickAddChoiceEngine {
 			this.choice.name,
 		);
 
-		return this.normalizeMarkdownFilePath("", formattedCaptureTo);
+		return this.normalizeCaptureFilePath(formattedCaptureTo);
+	}
+
+	private normalizeCaptureFilePath(path: string): string {
+		const normalizedPath = this.stripLeadingSlash(path);
+		if (BASE_FILE_EXTENSION_REGEX.test(normalizedPath)) {
+			throw new ChoiceAbortError(
+				`Capture to '.base' files is not supported (${normalizedPath}). Use a Template choice instead.`,
+			);
+		}
+		if (
+			MARKDOWN_FILE_EXTENSION_REGEX.test(normalizedPath) ||
+			CANVAS_FILE_EXTENSION_REGEX.test(normalizedPath)
+		) {
+			return normalizedPath;
+		}
+
+		return this.normalizeMarkdownFilePath("", normalizedPath);
 	}
 
 	private mergeCapturePropertyVars(vars: Map<string, unknown>): void {