refactor: adopt Fancy Kit UI and Vault harnesses

Author: vrtmrz

README.md

@@ -292,3 +292,7 @@ If the note has the tag that is set in here, the note would be treated as there
 Tags that were set here would be treated as there were not.
 
 ##### Archive tags
+
+## Development
+
+Contributor setup, tests, and UI/Vault workflow architecture are documented in [the developer guide](docs/devs.md).

docs/devs.md

@@ -0,0 +1,55 @@
+# Developer guide
+
+## Setup and checks
+
+Install the locked dependencies and run the repository gate:
+
+```bash
+npm ci
+npm run check
+npm run build
+```
+
+The App-free Vitest suite includes TagFolder tree utilities and the new-note application workflow.
+
+## UI and Vault boundaries
+
+The plug-in owns one `UiInteractions` capability and one `VaultTextAccess` capability for its lifetime:
+
+```ts
+this.ui = createObsidianUi(this.app);
+this.vaultText = createObsidianVaultTextAccess(this.app.vault);
+```
+
+`new-note-workflow.ts` accepts those capabilities instead of constructing an Obsidian template modal or reading and writing `TFile` instances directly. TagFolder still owns template variables, frontmatter policy, note creation, settings, and visible labels.
+
+Application-flow tests use instance-scoped App-free harnesses:
+
+```ts
+const ui = createUiTestHarness([
+	{ kind: "pickOne", interactionId: "new-note-template", value: template },
+]);
+const vault = createVaultTextTestHarness({
+	files: {
+		"Templates/project.md": "# {{tagName}}",
+		"Untitled.md": "",
+	},
+});
+```
+
+The UI transcript verifies the stable interaction ID and selected object identity. The Vault transcript verifies template reads, note writes, write ordering, and the absence of text writes when frontmatter owns the update.
+
+The path-based Vault capability deliberately does not replace real Obsidian coverage for `TFile` identity, Vault events, MetadataCache propagation, or frontmatter processing.
+
+## Fancy Kit preview
+
+Until Fancy Kit is published to npm, its packages are pinned to immutable tarballs from one GitHub prerelease. Update the UI interactions, Obsidian plug-in kit, and test-session URLs together when a migration needs a newer preview.
+
+Real-Obsidian scenarios are local-only and currently validated on Linux only.
+
+```bash
+npm run check:e2e:obsidian
+npm run test:e2e:obsidian:new-note-template
+```
+
+The real scenario uses the production UI and Vault adapters. It selects a template through Obsidian, creates a real note, and verifies the persisted content; it never installs a scripted driver into the plug-in.

main.ts

@@ -14,12 +14,16 @@ import {
 	Plugin,
 	PluginSettingTab,
 	Setting,
-	SuggestModal,
 	TFile,
 	WorkspaceLeaf,
 	TAbstractFile,
 	type MarkdownFileInfo,
 } from "obsidian";
+import { createObsidianUi, type UiInteractions } from "@vrtmrz/obsidian-plugin-kit/ui";
+import {
+	createObsidianVaultTextAccess,
+	type VaultTextAccess,
+} from "@vrtmrz/obsidian-plugin-kit/vault";
 
 import {
 	DEFAULT_SETTINGS,
@@ -56,7 +60,11 @@ import {
 	trimPrefix,
 	uniqueCaseIntensive
 } from "./util";
-import { renderTagFolderTemplateVariables } from "./new-note-template";
+import {
+	chooseNewNoteTemplate,
+	populateNewNote,
+	type NewNoteTemplateChoice,
+} from "./new-note-workflow";
 import { ScrollView } from "./ScrollView";
 import { TagFolderView } from "./TagFolderView";
 import { TagFolderList } from "./TagFolderList";
@@ -100,8 +108,6 @@ function getCompareMethodItems(settings: TagFolderSettings) {
 	}
 }
 
-type NewNoteTemplateChoice = TFile;
-
 function getCoreTemplatesFolder(app: App): string | null {
 	const internalPlugins = (app as App & {
 		internalPlugins?: {
@@ -135,44 +141,6 @@ function getTemplateFiles(app: App) {
 	return templates.sort((a, b) => compare(a.path, b.path));
 }
 
-class NewNoteTemplateSuggestModal extends SuggestModal<NewNoteTemplateChoice> {
-	private callback?: (template: NewNoteTemplateChoice | false) => void;
-	private templates: TFile[];
-
-	constructor(app: App, templates: TFile[], callback: (template: NewNoteTemplateChoice | false) => void) {
-		super(app);
-		this.templates = templates;
-		this.callback = callback;
-		this.setPlaceholder("Type to search templates...");
-	}
-
-	getSuggestions(query: string): NewNoteTemplateChoice[] {
-		const normalizedQuery = query.toLowerCase();
-		return this.templates.filter((file) =>
-			file.path.toLowerCase().contains(normalizedQuery)
-		);
-	}
-
-	renderSuggestion(template: NewNoteTemplateChoice, el: HTMLElement) {
-		el.createDiv({ text: template.basename });
-		el.createDiv({ text: template.path, cls: "suggestion-note" });
-	}
-
-	onChooseSuggestion(template: NewNoteTemplateChoice) {
-		this.callback?.(template);
-		this.callback = undefined;
-	}
-
-	onClose(): void {
-		window.setTimeout(() => {
-			if (this.callback) {
-				this.callback(false);
-				this.callback = undefined;
-			}
-		}, 100);
-	}
-}
-
 class NewNoteTemplateInputSuggest extends AbstractInputSuggest<TFile> {
 	private callback: (template: TFile) => void;
 
@@ -201,20 +169,19 @@ class NewNoteTemplateInputSuggest extends AbstractInputSuggest<TFile> {
 	}
 }
 
-function askNewNoteTemplate(app: App): Promise<NewNoteTemplateChoice | false> {
-	return new Promise((resolve) => {
-		const templates = getTemplateFiles(app);
-		if (templates.length == 0) {
-			new Notice("No templates found");
-			resolve(false);
-			return;
-		}
-		const modal = new NewNoteTemplateSuggestModal(app, templates, resolve);
-		modal.open();
-	});
+async function askNewNoteTemplate(ui: UiInteractions, app: App): Promise<NewNoteTemplateChoice | null> {
+	const templates = getTemplateFiles(app).map((file) => ({
+		path: file.path,
+		name: file.basename,
+	}));
+	if (templates.length == 0) {
+		new Notice("No templates found");
+		return null;
+	}
+	return await chooseNewNoteTemplate(ui, templates);
 }
 
-function getConfiguredNewNoteTemplate(app: App, templatePath: string): TFile | null {
+function getConfiguredNewNoteTemplate(app: App, templatePath: string): NewNoteTemplateChoice | null {
 	const inputPath = normalizeNewNoteTemplatePath(templatePath);
 	if (inputPath == "") return null;
 
@@ -240,7 +207,7 @@ function getConfiguredNewNoteTemplate(app: App, templatePath: string): TFile | n
 		return null;
 	}
 
-	return file;
+	return { path: file.path, name: file.basename };
 }
 
 function normalizeNewNoteTemplatePath(templatePath: string) {
@@ -260,6 +227,8 @@ function onElement<T extends HTMLElement | Document>(el: T, event: string, selec
 
 export default class TagFolderPlugin extends Plugin {
 	settings: TagFolderSettings = { ...DEFAULT_SETTINGS };
+	ui!: UiInteractions;
+	vaultText!: VaultTextAccess;
 
 	// Folder opening status.
 	expandedFolders: string[] = ["root"];
@@ -367,6 +336,8 @@ export default class TagFolderPlugin extends Plugin {
 
 	async onload() {
 		await this.loadSettings();
+		this.ui = createObsidianUi(this.app);
+		this.vaultText = createObsidianVaultTextAccess(this.app.vault);
 		this.hoverPreview = this.hoverPreview.bind(this);
 		this.modifyFile = this.modifyFile.bind(this);
 		this.setSearchString = this.setSearchString.bind(this);
@@ -1402,31 +1373,28 @@ export default class TagFolderPlugin extends Plugin {
 		const selectedTemplate = configuredTemplatePath == ""
 			? null
 			: (getConfiguredNewNoteTemplate(this.app, configuredTemplatePath)
-				?? await askNewNoteTemplate(this.app));
+				?? await askNewNoteTemplate(this.ui, this.app));
 
 		//@ts-ignore
 		const ww = await this.app.fileManager.createAndOpenMarkdownFile();
 		if (!(ww instanceof TFile)) return;
-		if (selectedTemplate != null && selectedTemplate !== false) {
-			const template = await this.app.vault.read(selectedTemplate);
-			const renderedTemplate = renderTagFolderTemplateVariables(template, expandedTagsAll, expandedTags);
-			if (renderedTemplate.trim() != "") {
-				await this.app.vault.modify(ww, renderedTemplate);
-			}
-			return;
-		}
-
-		if (this.settings.useFrontmatterTagsForNewNotes) {
-			await this.app.fileManager.processFrontMatter(ww, (matter) => {
-				matter.tags = matter.tags ?? [];
-				matter.tags = expandedTagsAll
-					.filter(e => !isSpecialTag(e))
-					.filter(e => matter.tags.indexOf(e) < 0)
-					.concat(matter.tags);
-			});
-		} else {
-			await this.app.vault.append(ww, expandedTags);
-		}
+		await populateNewNote({
+			vault: this.vaultText,
+			notePath: ww.path,
+			template: selectedTemplate,
+			expandedTagsAll,
+			expandedTags,
+			frontmatterTags: expandedTagsAll.filter(e => !isSpecialTag(e)),
+			useFrontmatterTags: this.settings.useFrontmatterTagsForNewNotes,
+			applyFrontmatterTags: async (frontmatterTags) => {
+				await this.app.fileManager.processFrontMatter(ww, (matter) => {
+					matter.tags = matter.tags ?? [];
+					matter.tags = frontmatterTags
+						.filter(e => matter.tags.indexOf(e) < 0)
+						.concat(matter.tags);
+				});
+			},
+		});
 	}
 }
 

new-note-workflow.ts

@@ -0,0 +1,73 @@
+import type { UiInteractions } from "@vrtmrz/obsidian-plugin-kit/ui";
+import type { VaultTextAccess } from "@vrtmrz/obsidian-plugin-kit/vault";
+import { renderTagFolderTemplateVariables } from "./new-note-template";
+
+export const NEW_NOTE_TEMPLATE_INTERACTION_ID = "new-note-template";
+
+/** Template identity and labels exposed to the application workflow. */
+export interface NewNoteTemplateChoice {
+	/** Vault-relative template path. */
+	readonly path: string;
+	/** Primary visible template name. */
+	readonly name: string;
+}
+
+/** Requests one template by identity, or returns `null` when dismissed or empty. */
+export async function chooseNewNoteTemplate(
+	ui: UiInteractions,
+	templates: readonly NewNoteTemplateChoice[],
+): Promise<NewNoteTemplateChoice | null> {
+	if (templates.length == 0) return null;
+	return await ui.pickOne(
+		{
+			items: templates,
+			getText: (template) => template.name,
+			getDescription: (template) => template.path,
+			placeholder: "Type to search templates...",
+		},
+		NEW_NOTE_TEMPLATE_INTERACTION_ID,
+	);
+}
+
+/** Inputs owned by TagFolder while populating a newly created note. */
+export interface PopulateNewNoteOptions {
+	/** Injectable path-based Vault text capability. */
+	readonly vault: VaultTextAccess;
+	/** Vault-relative path of the already created note. */
+	readonly notePath: string;
+	/** Selected template, or `null` to apply tags without a template. */
+	readonly template: NewNoteTemplateChoice | null;
+	/** Expanded tags used by template variables. */
+	readonly expandedTagsAll: readonly string[];
+	/** Expanded hashtag string used by template variables or body append. */
+	readonly expandedTags: string;
+	/** Non-special tags supplied to the frontmatter callback. */
+	readonly frontmatterTags: readonly string[];
+	/** Whether no-template tags should be written through frontmatter. */
+	readonly useFrontmatterTags: boolean;
+	/** Consumer-owned Obsidian frontmatter mutation. */
+	readonly applyFrontmatterTags: (tags: readonly string[]) => Promise<void>;
+}
+
+/** Populates a new note from a template, frontmatter tags, or appended hashtags. */
+export async function populateNewNote(options: PopulateNewNoteOptions): Promise<void> {
+	if (options.template !== null) {
+		const template = await options.vault.readText(options.template.path);
+		const renderedTemplate = renderTagFolderTemplateVariables(
+			template,
+			[...options.expandedTagsAll],
+			options.expandedTags,
+		);
+		if (renderedTemplate.trim() != "") {
+			await options.vault.modifyText(options.notePath, renderedTemplate);
+		}
+		return;
+	}
+
+	if (options.useFrontmatterTags) {
+		await options.applyFrontmatterTags(options.frontmatterTags);
+		return;
+	}
+
+	await options.vault.appendText(options.notePath, options.expandedTags);
+}