@real1ty-obsidian-plugins/utils 2.11.0 → 2.12.0

package/dist/file/link-parser.js

@@ -75,4 +75,63 @@ export function formatWikiLink(filePath) {
     }
     return `[[${trimmed}|${displayName}]]`;
 }
+/**
+ * Checks if a value is an Obsidian internal link in the format [[...]]
+ */
+export function isObsidianLink(value) {
+    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) {
+    var _a;
+    if (!isObsidianLink(linkString))
+        return null;
+    const trimmed = linkString.trim();
+    const linkContent = (_a = trimmed.match(/^\[\[(.+?)\]\]$/)) === null || _a === void 0 ? void 0 : _a[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) {
+    var _a;
+    const parsed = parseObsidianLink(linkString);
+    return (_a = parsed === null || parsed === void 0 ? void 0 : parsed.alias) !== null && _a !== void 0 ? _a : linkString;
+}
+/**
+ * Gets the file path from an Obsidian link
+ */
+export function getObsidianLinkPath(linkString) {
+    var _a;
+    const parsed = parseObsidianLink(linkString);
+    return (_a = parsed === null || parsed === void 0 ? void 0 : parsed.path) !== null && _a !== void 0 ? _a : linkString;
+}
 //# sourceMappingURL=link-parser.js.map

package/dist/file/link-parser.js.map

@@ -1 +1 @@
-{"version":3,"file":"link-parser.js","sourceRoot":"","sources":["../../src/file/link-parser.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,IAAY,EAAiB,EAAE;IACtE,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,8BAA8B,CAAC,CAAC;IACzD,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IAExB,MAAM,QAAQ,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IACjC,IAAI,CAAC,QAAQ;QAAE,OAAO,IAAI,CAAC;IAE3B,IAAI,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IAEpE,OAAO,QAAQ,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,GAAG,QAAQ,KAAK,CAAC;AAC/D,CAAC,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,UAAU,aAAa,CAAC,IAAY;IACzC,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;QACvC,OAAO,IAAI,CAAC;IACb,CAAC;IAED,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;IAE5B,0DAA0D;IAC1D,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,kCAAkC,CAAC,CAAC;IAEhE,IAAI,CAAC,KAAK,EAAE,CAAC;QACZ,OAAO,IAAI,CAAC;IACb,CAAC;IAED,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;AACxB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAoC;IACtE,IAAI,CAAC,KAAK,EAAE,CAAC;QACZ,OAAO,EAAE,CAAC;IACX,CAAC;IAED,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;IAErD,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,EAAkB,EAAE,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC;AACjG,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,QAAgB;IAC9C,IAAI,CAAC,QAAQ,IAAI,OAAO,QAAQ,KAAK,QAAQ,EAAE,CAAC;QAC/C,OAAO,EAAE,CAAC;IACX,CAAC;IAED,MAAM,OAAO,GAAG,QAAQ,CAAC,IAAI,EAAE,CAAC;IAEhC,IAAI,CAAC,OAAO,EAAE,CAAC;QACd,OAAO,EAAE,CAAC;IACX,CAAC;IAED,uDAAuD;IACvD,MAAM,QAAQ,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACpC,MAAM,WAAW,GAAG,QAAQ,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAElD,wDAAwD;IACxD,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC3B,OAAO,KAAK,OAAO,IAAI,CAAC;IACzB,CAAC;IAED,OAAO,KAAK,OAAO,IAAI,WAAW,IAAI,CAAC;AACxC,CAAC","sourcesContent":["/**\n * Handles different link formats and edge cases:\n * [[FileName]] -> FileName.md\n * [[Folder/FileName]] -> Folder/FileName.md\n * [[Folder/FileName|DisplayName]] -> Folder/FileName.md\n * Normalizes paths and handles malformed links gracefully.\n */\nexport const extractFilePathFromLink = (link: string): string | null => {\n\tconst match = link.match(/\\[\\[([^|\\]]+?)(?:\\|.*?)?\\]\\]/);\n\tif (!match) return null;\n\n\tconst filePath = match[1].trim();\n\tif (!filePath) return null;\n\n\tif (filePath.includes(\"[[\") || filePath.includes(\"]]\")) return null;\n\n\treturn filePath.endsWith(\".md\") ? filePath : `${filePath}.md`;\n};\n\n/**\n * Parses an Obsidian wiki link to extract the file path.\n * Handles formats like:\n * - [[path/to/file]]\n * - [[path/to/file|Display Name]]\n *\n * @param link - The wiki link string\n * @returns The file path without the [[ ]] brackets, or null if invalid\n */\nexport function parseWikiLink(link: string): string | null {\n\tif (!link || typeof link !== \"string\") {\n\t\treturn null;\n\t}\n\n\tconst trimmed = link.trim();\n\n\t// Match [[path/to/file]] or [[path/to/file|Display Name]]\n\tconst match = trimmed.match(/^\\[\\[([^\\]|]+)(?:\\|[^\\]]+)?\\]\\]$/);\n\n\tif (!match) {\n\t\treturn null;\n\t}\n\n\treturn match[1].trim();\n}\n\n/**\n * Parses a property value that can be a single link or an array of links.\n * Extracts file paths from all valid wiki links.\n *\n * @param value - The property value (string, string[], or undefined)\n * @returns Array of file paths, empty if no valid links found\n */\nexport function parsePropertyLinks(value: string | string[] | undefined): string[] {\n\tif (!value) {\n\t\treturn [];\n\t}\n\n\tconst links = Array.isArray(value) ? value : [value];\n\n\treturn links.map((link) => parseWikiLink(link)).filter((path): path is string => path !== null);\n}\n\n/**\n * Formats a file path as an Obsidian wiki link with display name.\n * Example: \"Projects/MyProject\" -> \"[[Projects/MyProject|MyProject]]\"\n *\n * @param filePath - The file path to format\n * @returns The formatted wiki link with display name alias\n */\nexport function formatWikiLink(filePath: string): string {\n\tif (!filePath || typeof filePath !== \"string\") {\n\t\treturn \"\";\n\t}\n\n\tconst trimmed = filePath.trim();\n\n\tif (!trimmed) {\n\t\treturn \"\";\n\t}\n\n\t// Extract the filename (last segment after the last /)\n\tconst segments = trimmed.split(\"/\");\n\tconst displayName = segments[segments.length - 1];\n\n\t// If there's no path separator, just return simple link\n\tif (segments.length === 1) {\n\t\treturn `[[${trimmed}]]`;\n\t}\n\n\treturn `[[${trimmed}|${displayName}]]`;\n}\n"]}
+{"version":3,"file":"link-parser.js","sourceRoot":"","sources":["../../src/file/link-parser.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Handles different link formats and edge cases:\n * [[FileName]] -> FileName.md\n * [[Folder/FileName]] -> Folder/FileName.md\n * [[Folder/FileName|DisplayName]] -> Folder/FileName.md\n * Normalizes paths and handles malformed links gracefully.\n */\nexport const extractFilePathFromLink = (link: string): string | null => {\n\tconst match = link.match(/\\[\\[([^|\\]]+?)(?:\\|.*?)?\\]\\]/);\n\tif (!match) return null;\n\n\tconst filePath = match[1].trim();\n\tif (!filePath) return null;\n\n\tif (filePath.includes(\"[[\") || filePath.includes(\"]]\")) return null;\n\n\treturn filePath.endsWith(\".md\") ? filePath : `${filePath}.md`;\n};\n\n/**\n * Parses an Obsidian wiki link to extract the file path.\n * Handles formats like:\n * - [[path/to/file]]\n * - [[path/to/file|Display Name]]\n *\n * @param link - The wiki link string\n * @returns The file path without the [[ ]] brackets, or null if invalid\n */\nexport function parseWikiLink(link: string): string | null {\n\tif (!link || typeof link !== \"string\") {\n\t\treturn null;\n\t}\n\n\tconst trimmed = link.trim();\n\n\t// Match [[path/to/file]] or [[path/to/file|Display Name]]\n\tconst match = trimmed.match(/^\\[\\[([^\\]|]+)(?:\\|[^\\]]+)?\\]\\]$/);\n\n\tif (!match) {\n\t\treturn null;\n\t}\n\n\treturn match[1].trim();\n}\n\n/**\n * Parses a property value that can be a single link or an array of links.\n * Extracts file paths from all valid wiki links.\n *\n * @param value - The property value (string, string[], or undefined)\n * @returns Array of file paths, empty if no valid links found\n */\nexport function parsePropertyLinks(value: string | string[] | undefined): string[] {\n\tif (!value) {\n\t\treturn [];\n\t}\n\n\tconst links = Array.isArray(value) ? value : [value];\n\n\treturn links.map((link) => parseWikiLink(link)).filter((path): path is string => path !== null);\n}\n\n/**\n * Formats a file path as an Obsidian wiki link with display name.\n * Example: \"Projects/MyProject\" -> \"[[Projects/MyProject|MyProject]]\"\n *\n * @param filePath - The file path to format\n * @returns The formatted wiki link with display name alias\n */\nexport function formatWikiLink(filePath: string): string {\n\tif (!filePath || typeof filePath !== \"string\") {\n\t\treturn \"\";\n\t}\n\n\tconst trimmed = filePath.trim();\n\n\tif (!trimmed) {\n\t\treturn \"\";\n\t}\n\n\t// Extract the filename (last segment after the last /)\n\tconst segments = trimmed.split(\"/\");\n\tconst displayName = segments[segments.length - 1];\n\n\t// If there's no path separator, just return simple link\n\tif (segments.length === 1) {\n\t\treturn `[[${trimmed}]]`;\n\t}\n\n\treturn `[[${trimmed}|${displayName}]]`;\n}\n\n/**\n * Represents a parsed Obsidian link with its components\n */\nexport interface ObsidianLink {\n\traw: string;\n\tpath: string;\n\talias: string;\n}\n\n/**\n * Checks if a value is an Obsidian internal link in the format [[...]]\n */\nexport function isObsidianLink(value: unknown): boolean {\n\tif (typeof value !== \"string\") return false;\n\tconst trimmed = value.trim();\n\treturn /^\\[\\[.+\\]\\]$/.test(trimmed);\n}\n\n/**\n * Parses an Obsidian internal link and extracts its components\n *\n * Supports both formats:\n * - Simple: [[Page Name]]\n * - With alias: [[Path/To/Page|Display Name]]\n */\nexport function parseObsidianLink(linkString: string): ObsidianLink | null {\n\tif (!isObsidianLink(linkString)) return null;\n\n\tconst trimmed = linkString.trim();\n\tconst linkContent = trimmed.match(/^\\[\\[(.+?)\\]\\]$/)?.[1];\n\n\tif (!linkContent) return null;\n\n\t// Handle pipe syntax: [[path|display]]\n\tif (linkContent.includes(\"|\")) {\n\t\tconst parts = linkContent.split(\"|\");\n\t\tconst path = parts[0].trim();\n\t\tconst alias = parts.slice(1).join(\"|\").trim(); // Handle multiple pipes\n\n\t\treturn {\n\t\t\traw: trimmed,\n\t\t\tpath,\n\t\t\talias,\n\t\t};\n\t}\n\n\t// Simple format: [[path]]\n\tconst path = linkContent.trim();\n\treturn {\n\t\traw: trimmed,\n\t\tpath,\n\t\talias: path,\n\t};\n}\n\n/**\n * Gets the display alias from an Obsidian link\n */\nexport function getObsidianLinkAlias(linkString: string): string {\n\tconst parsed = parseObsidianLink(linkString);\n\treturn parsed?.alias ?? linkString;\n}\n\n/**\n * Gets the file path from an Obsidian link\n */\nexport function getObsidianLinkPath(linkString: string): string {\n\tconst parsed = parseObsidianLink(linkString);\n\treturn parsed?.path ?? linkString;\n}\n"]}

package/dist/string/filename-utils.d.ts

@@ -0,0 +1,46 @@
+/**
+ * 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 declare const normalizeDirectoryPath: (directory: string) => string;
+/**
+ * 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 declare const extractDateAndSuffix: (basename: string) => {
+    dateStr: string;
+    suffix: string;
+} | null;
+/**
+ * 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 declare const rebuildPhysicalInstanceFilename: (currentBasename: string, newTitle: string) => string | null;
+//# sourceMappingURL=filename-utils.d.ts.map

package/dist/string/filename-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filename-utils.d.ts","sourceRoot":"","sources":["../../src/string/filename-utils.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,sBAAsB,GAAI,WAAW,MAAM,KAAG,MAE1D,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,oBAAoB,GAChC,UAAU,MAAM,KACd;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,IAWxC,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,+BAA+B,GAC3C,iBAAiB,MAAM,EACvB,UAAU,MAAM,KACd,MAAM,GAAG,IAaX,CAAC"}

package/dist/string/filename-utils.js

@@ -0,0 +1,65 @@
+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) => {
+    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) => {
+    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, newTitle) => {
+    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}`;
+};
+//# sourceMappingURL=filename-utils.js.map

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.12.0",
   "description": "Shared utilities for Obsidian plugins",
   "type": "module",
   "main": "./dist/index.js",

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/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";