@real1ty-obsidian-plugins/utils 2.10.0 → 2.12.0

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/string/filename-utils.ts

@@ -0,0 +1,77 @@
+import { sanitizeFilenamePreserveSpaces } from "../file/file";
+
+/**
+ * Normalizes a directory path for consistent comparison.
+ *
+ * - Trims whitespace
+ * - Removes leading and trailing slashes
+ * - Converts empty/whitespace-only strings to empty string
+ *
+ * Examples:
+ * - "tasks/" → "tasks"
+ * - "/tasks" → "tasks"
+ * - "/tasks/" → "tasks"
+ * - "  tasks  " → "tasks"
+ * - "" → ""
+ * - "   " → ""
+ * - "tasks/homework" → "tasks/homework"
+ */
+export const normalizeDirectoryPath = (directory: string): string => {
+	return directory.trim().replace(/^\/+|\/+$/g, "");
+};
+
+/**
+ * Extracts the date and suffix (everything after the date) from a physical instance filename.
+ * Physical instance format: "[title] [date]-[ZETTELID]"
+ *
+ * @param basename - The filename without extension
+ * @returns Object with dateStr and suffix, or null if no date found
+ *
+ * @example
+ * extractDateAndSuffix("My Event 2025-01-15-ABC123") // { dateStr: "2025-01-15", suffix: "-ABC123" }
+ * extractDateAndSuffix("Invalid filename") // null
+ */
+export const extractDateAndSuffix = (
+	basename: string
+): { dateStr: string; suffix: string } | null => {
+	const dateMatch = basename.match(/(\d{4}-\d{2}-\d{2})/);
+	if (!dateMatch) {
+		return null;
+	}
+
+	const dateStr = dateMatch[1];
+	const dateIndex = basename.indexOf(dateStr);
+	const suffix = basename.substring(dateIndex + dateStr.length);
+
+	return { dateStr, suffix };
+};
+
+/**
+ * Rebuilds a physical instance filename with a new title while preserving the date and zettel ID.
+ * Physical instance format: "[title] [date]-[ZETTELID]"
+ *
+ * @param currentBasename - Current filename without extension
+ * @param newTitle - New title (with or without zettel ID - will be stripped)
+ * @returns New filename, or null if current filename format is invalid
+ *
+ * @example
+ * rebuildPhysicalInstanceFilename("Old Title 2025-01-15-ABC123", "New Title-XYZ789")
+ * // Returns: "New Title 2025-01-15-ABC123"
+ */
+export const rebuildPhysicalInstanceFilename = (
+	currentBasename: string,
+	newTitle: string
+): string | null => {
+	const dateAndSuffix = extractDateAndSuffix(currentBasename);
+	if (!dateAndSuffix) {
+		return null;
+	}
+
+	const { dateStr, suffix } = dateAndSuffix;
+
+	// Remove any zettel ID from the new title (just in case)
+	const newTitleClean = newTitle.replace(/-[A-Z0-9]{6}$/, "");
+	const newTitleSanitized = sanitizeFilenamePreserveSpaces(newTitleClean);
+
+	return `${newTitleSanitized} ${dateStr}${suffix}`;
+};

package/src/string/index.ts

@@ -1 +1,2 @@
+export * from "./filename-utils";
 export * from "./string";