@real1ty-obsidian-plugins/utils 2.11.0 → 2.14.0

package/dist/string/filename-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"filename-utils.js","sourceRoot":"","sources":["../../src/string/filename-utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,8BAA8B,EAAE,MAAM,cAAc,CAAC;AAE9D;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,SAAiB,EAAU,EAAE;IACnE,OAAO,SAAS,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,YAAY,EAAE,EAAE,CAAC,CAAC;AACnD,CAAC,CAAC;AAEF;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CACnC,QAAgB,EAC6B,EAAE;IAC/C,MAAM,SAAS,GAAG,QAAQ,CAAC,KAAK,CAAC,qBAAqB,CAAC,CAAC;IACxD,IAAI,CAAC,SAAS,EAAE,CAAC;QAChB,OAAO,IAAI,CAAC;IACb,CAAC;IAED,MAAM,OAAO,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC;IAC7B,MAAM,SAAS,GAAG,QAAQ,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IAC5C,MAAM,MAAM,GAAG,QAAQ,CAAC,SAAS,CAAC,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAE9D,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC;AAC5B,CAAC,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,+BAA+B,GAAG,CAC9C,eAAuB,EACvB,QAAgB,EACA,EAAE;IAClB,MAAM,aAAa,GAAG,oBAAoB,CAAC,eAAe,CAAC,CAAC;IAC5D,IAAI,CAAC,aAAa,EAAE,CAAC;QACpB,OAAO,IAAI,CAAC;IACb,CAAC;IAED,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,aAAa,CAAC;IAE1C,yDAAyD;IACzD,MAAM,aAAa,GAAG,QAAQ,CAAC,OAAO,CAAC,eAAe,EAAE,EAAE,CAAC,CAAC;IAC5D,MAAM,iBAAiB,GAAG,8BAA8B,CAAC,aAAa,CAAC,CAAC;IAExE,OAAO,GAAG,iBAAiB,IAAI,OAAO,GAAG,MAAM,EAAE,CAAC;AACnD,CAAC,CAAC","sourcesContent":["import { sanitizeFilenamePreserveSpaces } from \"../file/file\";\n\n/**\n * Normalizes a directory path for consistent comparison.\n *\n * - Trims whitespace\n * - Removes leading and trailing slashes\n * - Converts empty/whitespace-only strings to empty string\n *\n * Examples:\n * - \"tasks/\" → \"tasks\"\n * - \"/tasks\" → \"tasks\"\n * - \"/tasks/\" → \"tasks\"\n * - \"  tasks  \" → \"tasks\"\n * - \"\" → \"\"\n * - \"   \" → \"\"\n * - \"tasks/homework\" → \"tasks/homework\"\n */\nexport const normalizeDirectoryPath = (directory: string): string => {\n\treturn directory.trim().replace(/^\\/+|\\/+$/g, \"\");\n};\n\n/**\n * Extracts the date and suffix (everything after the date) from a physical instance filename.\n * Physical instance format: \"[title] [date]-[ZETTELID]\"\n *\n * @param basename - The filename without extension\n * @returns Object with dateStr and suffix, or null if no date found\n *\n * @example\n * extractDateAndSuffix(\"My Event 2025-01-15-ABC123\") // { dateStr: \"2025-01-15\", suffix: \"-ABC123\" }\n * extractDateAndSuffix(\"Invalid filename\") // null\n */\nexport const extractDateAndSuffix = (\n\tbasename: string\n): { dateStr: string; suffix: string } | null => {\n\tconst dateMatch = basename.match(/(\\d{4}-\\d{2}-\\d{2})/);\n\tif (!dateMatch) {\n\t\treturn null;\n\t}\n\n\tconst dateStr = dateMatch[1];\n\tconst dateIndex = basename.indexOf(dateStr);\n\tconst suffix = basename.substring(dateIndex + dateStr.length);\n\n\treturn { dateStr, suffix };\n};\n\n/**\n * Rebuilds a physical instance filename with a new title while preserving the date and zettel ID.\n * Physical instance format: \"[title] [date]-[ZETTELID]\"\n *\n * @param currentBasename - Current filename without extension\n * @param newTitle - New title (with or without zettel ID - will be stripped)\n * @returns New filename, or null if current filename format is invalid\n *\n * @example\n * rebuildPhysicalInstanceFilename(\"Old Title 2025-01-15-ABC123\", \"New Title-XYZ789\")\n * // Returns: \"New Title 2025-01-15-ABC123\"\n */\nexport const rebuildPhysicalInstanceFilename = (\n\tcurrentBasename: string,\n\tnewTitle: string\n): string | null => {\n\tconst dateAndSuffix = extractDateAndSuffix(currentBasename);\n\tif (!dateAndSuffix) {\n\t\treturn null;\n\t}\n\n\tconst { dateStr, suffix } = dateAndSuffix;\n\n\t// Remove any zettel ID from the new title (just in case)\n\tconst newTitleClean = newTitle.replace(/-[A-Z0-9]{6}$/, \"\");\n\tconst newTitleSanitized = sanitizeFilenamePreserveSpaces(newTitleClean);\n\n\treturn `${newTitleSanitized} ${dateStr}${suffix}`;\n};\n"]}

package/dist/string/index.d.ts

@@ -1,2 +1,3 @@
+export * from "./filename-utils";
 export * from "./string";
 //# sourceMappingURL=index.d.ts.map

package/dist/string/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/string/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/string/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,UAAU,CAAC"}

package/dist/string/index.js

@@ -1,2 +1,3 @@
+export * from "./filename-utils";
 export * from "./string";
 //# sourceMappingURL=index.js.map

package/dist/string/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/string/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC","sourcesContent":["export * from \"./string\";\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/string/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,UAAU,CAAC","sourcesContent":["export * from \"./filename-utils\";\nexport * from \"./string\";\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@real1ty-obsidian-plugins/utils",
-  "version": "2.11.0",
+  "version": "2.14.0",
   "description": "Shared utilities for Obsidian plugins",
   "type": "module",
   "main": "./dist/index.js",

package/src/components/index.ts

@@ -0,0 +1 @@
+export * from "./input-managers";

package/src/components/input-managers/base.ts

@@ -0,0 +1,150 @@
+export type InputManagerFilterChangeCallback = () => void;
+
+const DEFAULT_DEBOUNCE_MS = 150;
+
+export abstract class InputManager {
+	protected containerEl: HTMLElement;
+	protected inputEl: HTMLInputElement | null = null;
+	protected debounceTimer: number | null = null;
+	protected currentValue = "";
+	protected persistentlyVisible = false;
+	protected onHide?: () => void;
+	protected hiddenClass: string;
+	protected debounceMs: number;
+	protected cssClass: string;
+
+	constructor(
+		protected parentEl: HTMLElement,
+		protected placeholder: string,
+		protected cssPrefix: string,
+		protected onFilterChange: InputManagerFilterChangeCallback,
+		initiallyVisible: boolean,
+		onHide?: () => void,
+		debounceMs: number = DEFAULT_DEBOUNCE_MS
+	) {
+		this.hiddenClass = `${cssPrefix}-hidden`;
+		this.debounceMs = debounceMs;
+		this.cssClass = `${cssPrefix}-input`;
+
+		const classes = initiallyVisible
+			? `${cssPrefix}-container`
+			: `${cssPrefix}-container ${this.hiddenClass}`;
+
+		this.containerEl = this.parentEl.createEl("div", {
+			cls: classes,
+		});
+
+		this.onHide = onHide;
+
+		this.render();
+	}
+
+	private render(): void {
+		this.inputEl = this.containerEl.createEl("input", {
+			type: "text",
+			cls: this.cssClass,
+			placeholder: this.placeholder,
+		});
+
+		this.inputEl.addEventListener("input", () => {
+			this.handleInputChange();
+		});
+
+		this.inputEl.addEventListener("keydown", (evt) => {
+			if (evt.key === "Escape") {
+				// Only allow hiding if not persistently visible
+				if (!this.persistentlyVisible) {
+					this.hide();
+				} else {
+					// Just blur the input if persistently visible
+					this.inputEl?.blur();
+				}
+			} else if (evt.key === "Enter") {
+				this.applyFilterImmediately();
+			}
+		});
+	}
+
+	private handleInputChange(): void {
+		if (this.debounceTimer !== null) {
+			window.clearTimeout(this.debounceTimer);
+		}
+
+		this.debounceTimer = window.setTimeout(() => {
+			this.applyFilterImmediately();
+		}, this.debounceMs);
+	}
+
+	protected applyFilterImmediately(): void {
+		const newValue = this.inputEl?.value.trim() ?? "";
+
+		if (newValue !== this.currentValue) {
+			this.updateFilterValue(newValue);
+		}
+	}
+
+	protected updateFilterValue(value: string): void {
+		this.currentValue = value;
+
+		this.onFilterChange();
+	}
+
+	getCurrentValue(): string {
+		return this.currentValue;
+	}
+
+	show(): void {
+		this.containerEl.removeClass(this.hiddenClass);
+
+		this.inputEl?.focus();
+	}
+
+	hide(): void {
+		// Don't allow hiding if persistently visible
+		if (this.persistentlyVisible) {
+			return;
+		}
+
+		this.containerEl.addClass(this.hiddenClass);
+
+		if (this.inputEl) {
+			this.inputEl.value = "";
+		}
+
+		this.updateFilterValue("");
+
+		this.onHide?.();
+	}
+
+	focus(): void {
+		this.inputEl?.focus();
+	}
+
+	isVisible(): boolean {
+		return !this.containerEl.hasClass(this.hiddenClass);
+	}
+
+	setPersistentlyVisible(value: boolean): void {
+		this.persistentlyVisible = value;
+
+		if (value) {
+			this.show();
+		} else {
+			this.hide();
+		}
+	}
+
+	destroy(): void {
+		if (this.debounceTimer !== null) {
+			window.clearTimeout(this.debounceTimer);
+
+			this.debounceTimer = null;
+		}
+
+		this.containerEl.remove();
+
+		this.inputEl = null;
+	}
+
+	abstract shouldInclude(data: unknown): boolean;
+}

package/src/components/input-managers/expression.ts

@@ -0,0 +1,92 @@
+import { buildPropertyMapping, sanitizeExpression } from "../../core/expression-utils";
+
+import { InputManager } from "./base";
+
+export class ExpressionFilterInputManager extends InputManager {
+	private compiledFunc: ((...args: unknown[]) => boolean) | null = null;
+
+	private propertyMapping = new Map<string, string>();
+
+	private lastWarnedExpression: string | null = null;
+
+	constructor(
+		parentEl: HTMLElement,
+		cssPrefix: string,
+		onFilterChange: () => void,
+		initiallyVisible: boolean = false,
+		placeholder: string = "Status === 'Done'",
+		onHide?: () => void,
+		debounceMs?: number
+	) {
+		super(parentEl, placeholder, cssPrefix, onFilterChange, initiallyVisible, onHide, debounceMs);
+		this.cssClass = `${cssPrefix}-expression-input`;
+		if (this.inputEl) {
+			this.inputEl.className = this.cssClass;
+		}
+	}
+
+	protected updateFilterValue(filterValue: string): void {
+		super.updateFilterValue(filterValue);
+
+		this.compiledFunc = null;
+
+		this.propertyMapping.clear();
+
+		this.lastWarnedExpression = null;
+	}
+
+	shouldInclude(event: { meta?: Record<string, unknown> }): boolean {
+		if (!this.currentValue) return true;
+
+		const frontmatter = event.meta || {};
+
+		try {
+			const currentKeys = new Set(Object.keys(frontmatter));
+
+			const existingKeys = new Set(this.propertyMapping.keys());
+
+			const newKeys = [...currentKeys].filter((key) => !existingKeys.has(key));
+
+			if (newKeys.length > 0) {
+				const allKeys = new Set([...existingKeys, ...currentKeys]);
+
+				this.propertyMapping = buildPropertyMapping(Array.from(allKeys));
+
+				this.compiledFunc = null;
+			}
+
+			if (!this.compiledFunc) {
+				const sanitized = sanitizeExpression(this.currentValue, this.propertyMapping);
+
+				const params = Array.from(this.propertyMapping.values());
+
+				// eslint-disable-next-line @typescript-eslint/no-implied-eval -- Dynamic function creation for expression evaluation with sanitized input
+				this.compiledFunc = new Function(...params, `"use strict"; return ${sanitized};`) as (
+					...args: unknown[]
+				) => boolean;
+			}
+
+			const values = Array.from(this.propertyMapping.keys()).map(
+				(key) => frontmatter[key] ?? undefined
+			);
+
+			const result = this.compiledFunc(...values);
+
+			return result;
+		} catch (error) {
+			if (error instanceof ReferenceError) {
+				const hasInequality = this.currentValue.includes("!==") || this.currentValue.includes("!=");
+
+				return hasInequality;
+			}
+
+			if (this.lastWarnedExpression !== this.currentValue) {
+				console.warn("Invalid filter expression:", this.currentValue, error);
+
+				this.lastWarnedExpression = this.currentValue;
+			}
+
+			return false;
+		}
+	}
+}

package/src/components/input-managers/index.ts

@@ -0,0 +1,3 @@
+export * from "./base";
+export * from "./expression";
+export * from "./search";

package/src/components/input-managers/search.ts

@@ -0,0 +1,25 @@
+import { InputManager } from "./base";
+
+export class SearchFilterInputManager extends InputManager {
+	constructor(
+		parentEl: HTMLElement,
+		cssPrefix: string,
+		onFilterChange: () => void,
+		initiallyVisible: boolean = false,
+		placeholder: string = "Search ...",
+		onHide?: () => void,
+		debounceMs?: number
+	) {
+		super(parentEl, placeholder, cssPrefix, onFilterChange, initiallyVisible, onHide, debounceMs);
+		this.cssClass = `${cssPrefix}-search-input`;
+		if (this.inputEl) {
+			this.inputEl.className = this.cssClass;
+		}
+	}
+
+	shouldInclude(value: string): boolean {
+		if (!this.currentValue) return true;
+
+		return value.toLowerCase().includes(this.currentValue.toLowerCase());
+	}
+}

package/src/core/evaluator/base.ts

@@ -40,8 +40,17 @@ export abstract class BaseEvaluator<TRule extends BaseRule, TSettings> {
 		}
 
 		try {
-			if (this.propertyMapping.size === 0) {
-				this.propertyMapping = buildPropertyMapping(Object.keys(frontmatter));
+			// Progressively build property mapping as we encounter new properties
+			const currentKeys = new Set(Object.keys(frontmatter));
+			const existingKeys = new Set(this.propertyMapping.keys());
+			const newKeys = [...currentKeys].filter((key) => !existingKeys.has(key));
+
+			// If new properties are found, rebuild the mapping and invalidate compiled functions
+			if (newKeys.length > 0) {
+				const allKeys = new Set([...existingKeys, ...currentKeys]);
+				this.propertyMapping = buildPropertyMapping(Array.from(allKeys));
+				// Clear compiled functions since property mapping changed
+				this.compiledFunctions.clear();
 			}
 
 			let compiledFunc = this.compiledFunctions.get(rule.id);
@@ -55,7 +64,10 @@ export abstract class BaseEvaluator<TRule extends BaseRule, TSettings> {
 				this.compiledFunctions.set(rule.id, compiledFunc);
 			}
 
-			const values = Array.from(this.propertyMapping.keys()).map((key) => frontmatter[key]);
+			// Use undefined for missing properties instead of letting them be undefined implicitly
+			const values = Array.from(this.propertyMapping.keys()).map(
+				(key) => frontmatter[key] ?? undefined
+			);
 			const result = compiledFunc(...values);
 
 			return result === true;

package/src/core/index.ts

@@ -4,4 +4,5 @@ export * from "./evaluator";
 export * from "./expression-utils";
 export * from "./frontmatter-value";
 export * from "./generate";
+export * from "./property-renderer";
 export * from "./validation";

package/src/core/property-renderer.ts

@@ -0,0 +1,62 @@
+import { getObsidianLinkAlias, getObsidianLinkPath, isObsidianLink } from "../file/link-parser";
+
+export interface PropertyRendererConfig {
+	createLink: (text: string, path: string, isObsidianLink: boolean) => HTMLElement;
+	createText: (text: string) => HTMLElement | Text;
+	createSeparator?: () => HTMLElement | Text;
+}
+
+export function renderPropertyValue(
+	container: HTMLElement,
+	value: any,
+	config: PropertyRendererConfig
+): void {
+	// Handle arrays - render each item separately
+	if (Array.isArray(value)) {
+		const hasClickableLinks = value.some(isObsidianLink);
+
+		if (hasClickableLinks) {
+			for (let index = 0; index < value.length; index++) {
+				if (index > 0 && config.createSeparator) {
+					container.appendChild(config.createSeparator());
+				}
+				renderSingleValue(container, value[index], config);
+			}
+		} else {
+			// Plain array - just join with commas
+			const textNode = config.createText(value.join(", "));
+			container.appendChild(textNode);
+		}
+		return;
+	}
+
+	renderSingleValue(container, value, config);
+}
+
+function renderSingleValue(
+	container: HTMLElement,
+	value: any,
+	config: PropertyRendererConfig
+): void {
+	const stringValue = String(value).trim();
+
+	if (isObsidianLink(stringValue)) {
+		const displayText = getObsidianLinkAlias(stringValue);
+		const linkPath = getObsidianLinkPath(stringValue);
+		const link = config.createLink(displayText, linkPath, true);
+		container.appendChild(link);
+		return;
+	}
+
+	// Regular text
+	const textNode = config.createText(stringValue);
+	container.appendChild(textNode);
+}
+
+export function createTextNode(text: string): Text {
+	return document.createTextNode(text);
+}
+
+export function createDefaultSeparator(): Text {
+	return document.createTextNode(", ");
+}

package/src/file/file-utils.ts

@@ -0,0 +1,67 @@
+import type { App } from "obsidian";
+import { TFile } from "obsidian";
+
+/**
+ * Gets a TFile by path or throws an error if not found.
+ * Useful when you need to ensure a file exists before proceeding.
+ */
+export const getTFileOrThrow = (app: App, path: string): TFile => {
+	const f = app.vault.getAbstractFileByPath(path);
+	if (!(f instanceof TFile)) throw new Error(`File not found: ${path}`);
+	return f;
+};
+
+/**
+ * Executes an operation on a file's frontmatter.
+ * Wrapper around Obsidian's processFrontMatter for more concise usage.
+ */
+export const withFrontmatter = async (
+	app: App,
+	file: TFile,
+	update: (fm: Record<string, unknown>) => void
+) => app.fileManager.processFrontMatter(file, update);
+
+/**
+ * Creates a backup copy of a file's frontmatter.
+ * Useful for undo/redo operations or temporary modifications.
+ */
+export const backupFrontmatter = async (app: App, file: TFile) => {
+	let copy: Record<string, unknown> = {};
+	await withFrontmatter(app, file, (fm) => {
+		copy = { ...fm };
+	});
+	return copy;
+};
+
+/**
+ * Restores a file's frontmatter from a backup.
+ * Clears existing frontmatter and replaces with the backup.
+ */
+export const restoreFrontmatter = async (
+	app: App,
+	file: TFile,
+	original: Record<string, unknown>
+) =>
+	withFrontmatter(app, file, (fm) => {
+		for (const k of Object.keys(fm)) {
+			delete fm[k];
+		}
+		Object.assign(fm, original);
+	});
+
+/**
+ * Extracts the content that appears after the frontmatter section.
+ * Returns the entire content if no frontmatter is found.
+ */
+export const extractContentAfterFrontmatter = (fullContent: string): string => {
+	const frontmatterRegex = /^---\s*\n([\s\S]*?)\n---\s*\n/;
+	const match = fullContent.match(frontmatterRegex);
+
+	if (match) {
+		// Return content after frontmatter
+		return fullContent.substring(match.index! + match[0].length);
+	}
+
+	// If no frontmatter found, return the entire content
+	return fullContent;
+};

package/src/file/file.ts

@@ -548,16 +548,98 @@ export function findRootNodesInFolder(app: App, folderPath: string): string[] {
 }
 
 // ============================================================================
-// Legacy Utility Functions (kept for backwards compatibility)
+// Filename Sanitization
 // ============================================================================
 
-export const sanitizeForFilename = (input: string): string => {
-	return input
-		.replace(/[<>:"/\\|?*]/g, "") // Remove invalid filename characters
-		.replace(/\s+/g, "-") // Replace spaces with hyphens
-		.replace(/-+/g, "-") // Replace multiple hyphens with single
-		.replace(/^-|-$/g, "") // Remove leading/trailing hyphens
-		.toLowerCase();
+export interface SanitizeFilenameOptions {
+	/**
+	 * Style of sanitization to apply.
+	 * - "kebab": Convert to lowercase, replace spaces with hyphens (default, backwards compatible)
+	 * - "preserve": Preserve spaces and case, only remove invalid characters
+	 */
+	style?: "kebab" | "preserve";
+}
+
+/**
+ * Sanitizes a string for use as a filename.
+ * Defaults to kebab-case style for backwards compatibility.
+ *
+ * @param input - String to sanitize
+ * @param options - Sanitization options
+ * @returns Sanitized filename string
+ *
+ * @example
+ * // Default kebab-case style (backwards compatible)
+ * sanitizeForFilename("My File Name") // "my-file-name"
+ *
+ * // Preserve spaces and case
+ * sanitizeForFilename("My File Name", { style: "preserve" }) // "My File Name"
+ */
+export const sanitizeForFilename = (
+	input: string,
+	options: SanitizeFilenameOptions = {}
+): string => {
+	const { style = "kebab" } = options;
+
+	if (style === "preserve") {
+		return sanitizeFilenamePreserveSpaces(input);
+	}
+
+	// Default: kebab-case style (legacy behavior)
+	return sanitizeFilenameKebabCase(input);
+};
+
+/**
+ * Sanitizes filename using kebab-case style.
+ * - Removes invalid characters
+ * - Converts to lowercase
+ * - Replaces spaces with hyphens
+ *
+ * Best for: CLI tools, URLs, slugs, technical files
+ *
+ * @example
+ * sanitizeFilenameKebabCase("My File Name") // "my-file-name"
+ * sanitizeFilenameKebabCase("Travel Around The World") // "travel-around-the-world"
+ */
+export const sanitizeFilenameKebabCase = (input: string): string => {
+	return (
+		input
+			// Remove invalid filename characters
+			.replace(/[<>:"/\\|?*]/g, "")
+			// Replace spaces with hyphens
+			.replace(/\s+/g, "-")
+			// Replace multiple hyphens with single
+			.replace(/-+/g, "-")
+			// Remove leading/trailing hyphens
+			.replace(/^-|-$/g, "")
+			// Convert to lowercase
+			.toLowerCase()
+	);
+};
+
+/**
+ * Sanitizes filename while preserving spaces and case.
+ * - Removes invalid characters only
+ * - Preserves spaces and original casing
+ * - Removes trailing dots (Windows compatibility)
+ *
+ * Best for: Note titles, human-readable filenames, Obsidian notes
+ *
+ * @example
+ * sanitizeFilenamePreserveSpaces("My File Name") // "My File Name"
+ * sanitizeFilenamePreserveSpaces("Travel Around The World") // "Travel Around The World"
+ * sanitizeFilenamePreserveSpaces("File<Invalid>Chars") // "FileInvalidChars"
+ */
+export const sanitizeFilenamePreserveSpaces = (input: string): string => {
+	return (
+		input
+			// Remove invalid filename characters (cross-platform compatibility)
+			.replace(/[<>:"/\\|?*]/g, "")
+			// Remove trailing dots (invalid on Windows)
+			.replace(/\.+$/g, "")
+			// Remove leading/trailing whitespace
+			.trim()
+	);
 };
 
 export const getFilenameFromPath = (filePath: string): string => {

package/src/file/index.ts

@@ -1,6 +1,7 @@
 export * from "./child-reference";
 export * from "./file";
 export * from "./file-operations";
+export * from "./file-utils";
 export * from "./frontmatter";
 export * from "./link-parser";
 export * from "./property-utils";

package/src/file/link-parser.ts

@@ -89,3 +89,74 @@ export function formatWikiLink(filePath: string): string {
 
 	return `[[${trimmed}|${displayName}]]`;
 }
+
+/**
+ * Represents a parsed Obsidian link with its components
+ */
+export interface ObsidianLink {
+	raw: string;
+	path: string;
+	alias: string;
+}
+
+/**
+ * Checks if a value is an Obsidian internal link in the format [[...]]
+ */
+export function isObsidianLink(value: unknown): boolean {
+	if (typeof value !== "string") return false;
+	const trimmed = value.trim();
+	return /^\[\[.+\]\]$/.test(trimmed);
+}
+
+/**
+ * Parses an Obsidian internal link and extracts its components
+ *
+ * Supports both formats:
+ * - Simple: [[Page Name]]
+ * - With alias: [[Path/To/Page|Display Name]]
+ */
+export function parseObsidianLink(linkString: string): ObsidianLink | null {
+	if (!isObsidianLink(linkString)) return null;
+
+	const trimmed = linkString.trim();
+	const linkContent = trimmed.match(/^\[\[(.+?)\]\]$/)?.[1];
+
+	if (!linkContent) return null;
+
+	// Handle pipe syntax: [[path|display]]
+	if (linkContent.includes("|")) {
+		const parts = linkContent.split("|");
+		const path = parts[0].trim();
+		const alias = parts.slice(1).join("|").trim(); // Handle multiple pipes
+
+		return {
+			raw: trimmed,
+			path,
+			alias,
+		};
+	}
+
+	// Simple format: [[path]]
+	const path = linkContent.trim();
+	return {
+		raw: trimmed,
+		path,
+		alias: path,
+	};
+}
+
+/**
+ * Gets the display alias from an Obsidian link
+ */
+export function getObsidianLinkAlias(linkString: string): string {
+	const parsed = parseObsidianLink(linkString);
+	return parsed?.alias ?? linkString;
+}
+
+/**
+ * Gets the file path from an Obsidian link
+ */
+export function getObsidianLinkPath(linkString: string): string {
+	const parsed = parseObsidianLink(linkString);
+	return parsed?.path ?? linkString;
+}

package/src/index.ts

@@ -2,6 +2,8 @@
 
 // Async utilities
 export * from "./async";
+// Components
+export * from "./components";
 // Core utilities
 export * from "./core";