feat: add write to top of file switch for capture to active file (#986)

Adds a new option to insert capture content at the top of the active file
(after frontmatter) instead of at the cursor position. This addresses
the feature request in issue #248.

Changes:
- Add new 'activeFileTop' capture action type
- Add 'activeFileWritePosition' field to capture choice types
- Update UI to show separate 'At cursor' vs 'Top of file' options
- Update engine and formatter to handle the new action
- Add tests for the new functionality
- Ensure backward compatibility for existing choices

Closes #248

Author: chhoumann

src/engine/CaptureChoiceEngine.ts

@@ -73,6 +73,7 @@ export class CaptureChoiceEngine extends QuickAddChoiceEngine {
 				msg = `Captured to current line in ${fileName}`;
 				break;
 			case "prepend":
+			case "activeFileTop":
 				msg = `Captured to top of ${fileName}`;
 				break;
 			case "append":
@@ -127,10 +128,14 @@ export class CaptureChoiceEngine extends QuickAddChoiceEngine {
 			const { file, newFileContent, captureContent } =
 				await getFileAndAddContentFn(filePath, content);
 
-			const action = getCaptureAction(this.choice);
+		const action = getCaptureAction(this.choice);
+		const isEditorInsertionAction =
+			action === "currentLine" ||
+			action === "newLineAbove" ||
+			action === "newLineBelow";
 
-			// Handle capture to active file with special actions
-			if (action === "currentLine" || action === "newLineAbove" || action === "newLineBelow") {
+		// Handle capture to active file with special actions
+		if (isEditorInsertionAction) {
 				// Parse Templater syntax in the capture content.
 				// If Templater isn't installed, it just returns the capture content.
 				const content = await templaterParseTemplate(
@@ -158,7 +163,6 @@ export class CaptureChoiceEngine extends QuickAddChoiceEngine {
 
 			// Show success notification
 			if (this.plugin.settings.showCaptureNotification) {
-				const action = getCaptureAction(this.choice);
 				this.showSuccessNotice(file, {
 					wasNewFile: !fileAlreadyExists,
 					action,
@@ -203,15 +207,15 @@ export class CaptureChoiceEngine extends QuickAddChoiceEngine {
 	}
 
 	/**
-	 * Gets a formatted file path to capture content to, either the active file or a specified location.
-	 * If capturing to a folder, suggests a file within the folder to capture the content to.
-	 *
-	 * @param {boolean} shouldCaptureToActiveFile - Determines if the content should be captured to the active file.
-	 * @returns {Promise<string>} A promise that resolves to the formatted file path where the content should be captured.
-	 *
-	 * @throws {Error} Throws an error if there's no active file when trying to capture to active file,
-	 *                 if the capture path is invalid, or if the target folder is empty.
-	 */
+		* Gets a formatted file path to capture content to, either the active file or a specified location.
+		* If capturing to a folder, suggests a file within the folder to capture the content to.
+		*
+		* @param {boolean} shouldCaptureToActiveFile - Determines if the content should be captured to the active file.
+		* @returns {Promise<string>} A promise that resolves to the formatted file path where the content should be captured.
+		*
+		* @throws {Error} Throws an error if there's no active file when trying to capture to active file,
+		*                 if the capture path is invalid, or if the target folder is empty.
+		*/
 	private async getFormattedPathToCaptureTo(
 		shouldCaptureToActiveFile: boolean,
 	): Promise<string> {

src/engine/captureAction.test.ts

@@ -10,6 +10,7 @@ describe("getCaptureAction", () => {
 		command: false,
 		captureTo: "",
 		captureToActiveFile: false,
+		activeFileWritePosition: "cursor",
 		createFileIfItDoesntExist: { enabled: false, createWithTemplate: false, template: "" },
 		format: { enabled: false, format: "" },
 		prepend: false,
@@ -78,4 +79,30 @@ describe("getCaptureAction", () => {
 		});
 		expect(getCaptureAction(choice)).toBe("newLineBelow");
 	});
+
+	it("returns 'activeFileTop' when capturing to active file with write position set to top", () => {
+		const choice = createChoice({
+			captureToActiveFile: true,
+			activeFileWritePosition: "top",
+		});
+		expect(getCaptureAction(choice)).toBe("activeFileTop");
+	});
+
+	it("returns 'currentLine' when capturing to active file with default cursor position", () => {
+		const choice = createChoice({
+			captureToActiveFile: true,
+			activeFileWritePosition: "cursor",
+		});
+		expect(getCaptureAction(choice)).toBe("currentLine");
+	});
+
+	it("prioritizes 'activeFileTop' over the default append action when eligible", () => {
+		const choice = createChoice({
+			captureToActiveFile: true,
+			activeFileWritePosition: "top",
+			prepend: false,
+			insertAfter: { enabled: false, after: "", insertAtEnd: false, considerSubsections: false, createIfNotFound: false, createIfNotFoundLocation: "" },
+		});
+		expect(getCaptureAction(choice)).toBe("activeFileTop");
+	});
 });

src/engine/captureAction.ts

@@ -1,6 +1,6 @@
 import type ICaptureChoice from "../types/choices/ICaptureChoice";
 
-export type CaptureAction = "append" | "prepend" | "insertAfter" | "currentLine" | "newLineAbove" | "newLineBelow";
+export type CaptureAction = "append" | "prepend" | "insertAfter" | "currentLine" | "newLineAbove" | "newLineBelow" | "activeFileTop";
 
 /**
  * Gets the capture action based on choice configuration.
@@ -12,6 +12,10 @@ export function getCaptureAction(choice: ICaptureChoice): CaptureAction {
 	}
 
 	if (choice.captureToActiveFile && !choice.prepend && !choice.insertAfter.enabled) {
+		if (choice.activeFileWritePosition === "top") {
+			return "activeFileTop";
+		}
+
 		return "currentLine";
 	}
 

src/formatters/captureChoiceFormatter.ts

@@ -68,7 +68,8 @@ export class CaptureChoiceFormatter extends CompleteFormatter {
 		const shouldRunTemplater =
 			choice.insertAfter.enabled ||
 			choice.prepend ||
-			!choice.captureToActiveFile;
+			!choice.captureToActiveFile ||
+			choice.activeFileWritePosition === "top";
 		const formatted = await this.formatFileContent(input, shouldRunTemplater);
 		return formatted;
 	}

src/gui/ChoiceBuilder/captureChoiceBuilder.ts

@@ -290,6 +290,11 @@ export class CaptureChoiceBuilder extends ChoiceBuilder {
 	private addWritePositionSetting() {
 		const positionSetting: Setting = new Setting(this.contentEl);
 		const isActiveFile = !!this.choice?.captureToActiveFile;
+
+		if (!this.choice.activeFileWritePosition) {
+			this.choice.activeFileWritePosition = "cursor";
+		}
+
 		positionSetting
 			.setName("Write position")
 			.setDesc(
@@ -298,7 +303,7 @@ export class CaptureChoiceBuilder extends ChoiceBuilder {
 					: "Where to place the capture in the target file.",
 			)
 			.addDropdown((dropdown) => {
-				const current: "top" | "after" | "bottom" | "newLineAbove" | "newLineBelow" =
+				const current =
 					this.choice.insertAfter?.enabled
 						? "after"
 						: this.choice.prepend
@@ -307,12 +312,14 @@ export class CaptureChoiceBuilder extends ChoiceBuilder {
 								? this.choice.newLineCapture.direction === "above"
 									? "newLineAbove"
 									: "newLineBelow"
-								: "top";
+								: isActiveFile && this.choice.activeFileWritePosition === "top"
+									? "activeTop"
+									: "top";
 
 				dropdown.addOption("top", isActiveFile ? "At cursor" : "Top of file");
 
-				// Add new line options only when capturing to active file
 				if (isActiveFile) {
+					dropdown.addOption("activeTop", "Top of file (after frontmatter)");
 					dropdown.addOption("newLineAbove", "New line above cursor");
 					dropdown.addOption("newLineBelow", "New line below cursor");
 				}
@@ -321,21 +328,35 @@ export class CaptureChoiceBuilder extends ChoiceBuilder {
 				dropdown.addOption("bottom", "Bottom of file");
 				dropdown.setValue(current);
 				dropdown.onChange((value: string) => {
-					const v = value as "top" | "after" | "bottom" | "newLineAbove" | "newLineBelow";
+					const v = value as
+						| "top"
+						| "after"
+						| "bottom"
+						| "newLineAbove"
+						| "newLineBelow"
+						| "activeTop";
 
-					// Reset all options first
 					this.choice.prepend = false;
 					this.choice.insertAfter.enabled = false;
 					if (!this.choice.newLineCapture) {
 						this.choice.newLineCapture = { enabled: false, direction: "below" };
 					}
 					this.choice.newLineCapture.enabled = false;
+					this.choice.activeFileWritePosition = "cursor";
 
 					if (v === "top") {
 						this.reload();
 						return;
 					}
 
+					if (v === "activeTop") {
+						if (isActiveFile) {
+							this.choice.activeFileWritePosition = "top";
+						}
+						this.reload();
+						return;
+					}
+
 					if (v === "bottom") {
 						this.choice.prepend = true;
 						this.reload();

src/types/choices/CaptureChoice.ts

@@ -7,6 +7,7 @@ export class CaptureChoice extends Choice implements ICaptureChoice {
 	appendLink: boolean | AppendLinkOptions;
 	captureTo: string;
 	captureToActiveFile: boolean;
+	activeFileWritePosition: "cursor" | "top";
 	createFileIfItDoesntExist: {
 		enabled: boolean;
 		createWithTemplate: boolean;
@@ -41,6 +42,7 @@ export class CaptureChoice extends Choice implements ICaptureChoice {
 		this.appendLink = false;
 		this.captureTo = "";
 		this.captureToActiveFile = false;
+		this.activeFileWritePosition = "cursor";
 		this.createFileIfItDoesntExist = {
 			enabled: false,
 			createWithTemplate: false,
@@ -71,6 +73,11 @@ export class CaptureChoice extends Choice implements ICaptureChoice {
 	}
 
 	public static Load(choice: ICaptureChoice): CaptureChoice {
-		return choice as CaptureChoice;
+		const loaded = choice as CaptureChoice;
+		// Ensure backward compatibility: default to "cursor" if not set
+		if (!loaded.activeFileWritePosition) {
+			loaded.activeFileWritePosition = "cursor";
+		}
+		return loaded;
 	}
 }

src/types/choices/ICaptureChoice.ts

@@ -5,6 +5,7 @@ import type { OpenLocation, FileViewMode2 } from "../fileOpening";
 export default interface ICaptureChoice extends IChoice {
 	captureTo: string;
 	captureToActiveFile: boolean;
+	activeFileWritePosition?: "cursor" | "top";
 	createFileIfItDoesntExist: {
 		enabled: boolean;
 		createWithTemplate: boolean;
@@ -14,10 +15,10 @@ export default interface ICaptureChoice extends IChoice {
 	/** Capture to bottom of file (after current file content). */
 	prepend: boolean;
 	/** 
-	 * Configure link appending behavior. 
-	 * - boolean: Legacy format for backward compatibility (true = enabled with default placement)
-	 * - AppendLinkOptions: New format with configurable placement options
-	 */
+		* Configure link appending behavior.
+		* - boolean: Legacy format for backward compatibility (true = enabled with default placement)
+		* - AppendLinkOptions: New format with configurable placement options
+		*/
 	appendLink: boolean | AppendLinkOptions;
 	task: boolean;
 	insertAfter: {