feat: support callback function in titleTemplate.template option (#36)

* feat: support callback function in titleTemplate.template option

* Add purple-kings-build.md

Author: morinokami

.changeset/purple-kings-build.md

@@ -0,0 +1,5 @@
+---
+"tanstack-meta": minor
+---
+
+feat: support callback function in titleTemplate.template option

packages/meta/README.md

@@ -39,7 +39,7 @@ export const Route = createFileRoute("/")({
 
     return { meta, links };
   },
-})
+});
 ```
 
 You can use it almost the same way as Next.js's [`generateMetadata`](https://nextjs.org/docs/app/api-reference/functions/generate-metadata) function.
@@ -55,25 +55,50 @@ import { createMetadataGenerator } from "tanstack-meta";
 const generateMetadata = createMetadataGenerator({
   titleTemplate: {
     default: "Default Title", // Used when title is not provided
-    template: "%s | My Site"  // %s is replaced with the page title
-  }
+    template: "%s | My Site", // %s is replaced with the page title
+  },
 });
 
 // In your routes:
-generateMetadata({ title: "About" })
+generateMetadata({ title: "About" });
 // Output: <title>About | My Site</title>
 
-generateMetadata({ title: null })
+generateMetadata({ title: null });
 // Output: <title>Default Title</title>
 
-generateMetadata({})
+generateMetadata({});
 // Output: <title>Default Title</title>
 ```
 
+You can also use a function for more complex title transformations:
+
+```ts
+const generateMetadata = createMetadataGenerator({
+  titleTemplate: {
+    default: "My Site",
+    template: (title) => `${title.toUpperCase()} — My Site`,
+  },
+});
+
+generateMetadata({ title: "about" });
+// Output: <title>ABOUT — My Site</title>
+
+// Conditional logic example
+const generateMetadata = createMetadataGenerator({
+  titleTemplate: {
+    default: "My Site",
+    template: (title) =>
+      title.length > 50
+        ? `${title.slice(0, 47)}... | My Site`
+        : `${title} | My Site`,
+  },
+});
+```
+
 To opt out of the title template on a specific page, use `title.absolute`:
 
 ```ts
-generateMetadata({ title: { absolute: "Home" } })
+generateMetadata({ title: { absolute: "Home" } });
 // Output: <title>Home</title> (template is ignored)
 ```
 
@@ -87,18 +112,18 @@ Similar to Next.js's `metadataBase`, you can use the `baseUrl` option to resolve
 import { createMetadataGenerator } from "tanstack-meta";
 
 const generateMetadata = createMetadataGenerator({
-  baseUrl: "https://example.com"
+  baseUrl: "https://example.com",
 });
 
 // Relative URLs are resolved to absolute URLs
 generateMetadata({
   openGraph: {
-    images: "/og.png"
+    images: "/og.png",
   },
   alternates: {
-    canonical: "/about"
-  }
-})
+    canonical: "/about",
+  },
+});
 // Output:
 // <meta property="og:image" content="https://example.com/og.png" />
 // <link rel="canonical" href="https://example.com/about" />
@@ -108,7 +133,7 @@ You can also pass a `URL` object:
 
 ```ts
 const generateMetadata = createMetadataGenerator({
-  baseUrl: new URL("https://example.com")
+  baseUrl: new URL("https://example.com"),
 });
 ```
 
@@ -117,9 +142,9 @@ Absolute URLs are preserved unchanged:
 ```ts
 generateMetadata({
   openGraph: {
-    images: "https://cdn.example.com/og.png"
-  }
-})
+    images: "https://cdn.example.com/og.png",
+  },
+});
 // Output: <meta property="og:image" content="https://cdn.example.com/og.png" />
 ```
 
@@ -128,15 +153,15 @@ You can combine `baseUrl` with `titleTemplate`:
 ```ts
 const generateMetadata = createMetadataGenerator({
   titleTemplate: { default: "My Site", template: "%s | My Site" },
-  baseUrl: "https://example.com"
+  baseUrl: "https://example.com",
 });
 
 generateMetadata({
   title: "About",
   openGraph: {
-    images: "/og.png"
-  }
-})
+    images: "/og.png",
+  },
+});
 // Output:
 // <title>About | My Site</title>
 // <meta property="og:image" content="https://example.com/og.png" />
@@ -166,7 +191,7 @@ An options object with the following properties:
 
 - `titleTemplate` (optional): An object containing:
   - `default`: The default title used when no title is provided
-  - `template`: A template string where `%s` is replaced with the page title
+  - `template`: A template string where `%s` is replaced with the page title, or a function that receives the page title and returns the formatted title
 - `baseUrl` (optional): A string or `URL` object used to resolve relative URLs to absolute URLs. Applies to:
   - `openGraph` (images, audio, videos, url)
   - `twitter` (images, players, app URLs)

packages/meta/src/index.ts

@@ -3,7 +3,7 @@ import { meta } from "./meta";
 import { normalizeMetadata } from "./normalize";
 import { resolveAlternates } from "./resolve/alternates";
 import { resolveOpenGraph } from "./resolve/opengraph";
-import { resolveTitle } from "./resolve/title";
+import { resolveTitle, type TitleTemplate } from "./resolve/title";
 import { resolveTwitter } from "./resolve/twitter";
 import type {
 	GeneratorInputMetadata,
@@ -28,7 +28,7 @@ export function generateMetadata(metadata: InputMetadata): OutputMetadata {
 
 export function createMetadataGenerator(
 	options: {
-		titleTemplate?: { default: string; template: string };
+		titleTemplate?: TitleTemplate;
 		baseUrl?: string | URL | null;
 	} = {},
 ): (metadata: GeneratorInputMetadata) => OutputMetadata {
@@ -49,4 +49,9 @@ export function createMetadataGenerator(
 	};
 }
 
-export type { InputMetadata, OutputMetadata, GeneratorInputMetadata };
+export type {
+	InputMetadata,
+	OutputMetadata,
+	GeneratorInputMetadata,
+	TitleTemplate,
+};

packages/meta/src/resolve/title.test.ts

@@ -100,4 +100,74 @@ describe("resolveTitle", () => {
 			expect(result).toBe("Docs | Docs | Site");
 		});
 	});
+
+	describe("with template function", () => {
+		test("applies template function to string title", () => {
+			const result = resolveTitle(
+				{ title: "About" },
+				{ default: "My Site", template: (title) => `${title} | My Site` },
+			);
+
+			expect(result).toBe("About | My Site");
+		});
+
+		test("allows complex transformations", () => {
+			const result = resolveTitle(
+				{ title: "hello world" },
+				{
+					default: "My Site",
+					template: (title) => `${title.toUpperCase()} — My Site`,
+				},
+			);
+
+			expect(result).toBe("HELLO WORLD — My Site");
+		});
+
+		test("uses default when title is null with template function", () => {
+			const result = resolveTitle(
+				{ title: null },
+				{ default: "My Site", template: (title) => `${title} | My Site` },
+			);
+
+			expect(result).toBe("My Site");
+		});
+
+		test("uses default when title is undefined with template function", () => {
+			const result = resolveTitle(
+				{},
+				{ default: "My Site", template: (title) => `${title} | My Site` },
+			);
+
+			expect(result).toBe("My Site");
+		});
+
+		test("ignores template function when title is absolute", () => {
+			const result = resolveTitle(
+				{ title: { absolute: "Home" } },
+				{ default: "My Site", template: (title) => `${title} | My Site` },
+			);
+
+			expect(result).toBe("Home");
+		});
+
+		test("supports conditional logic in template function", () => {
+			const result = resolveTitle(
+				{
+					title:
+						"This is a very long title that exceeds fifty characters in length",
+				},
+				{
+					default: "My Site",
+					template: (title) =>
+						title.length > 50
+							? `${title.slice(0, 47)}... | My Site`
+							: `${title} | My Site`,
+				},
+			);
+
+			expect(result).toBe(
+				"This is a very long title that exceeds fifty ch... | My Site",
+			);
+		});
+	});
 });

packages/meta/src/resolve/title.ts

@@ -1,8 +1,13 @@
 import type { GeneratorInputMetadata, InputMetadata } from "../types/io";
 
+export type TitleTemplate = {
+	default: string;
+	template: string | ((title: string) => string);
+};
+
 export function resolveTitle(
 	metadata: GeneratorInputMetadata,
-	titleTemplate?: { default: string; template: string },
+	titleTemplate?: TitleTemplate,
 ): InputMetadata["title"] {
 	let title: string | null | undefined;
 
@@ -17,7 +22,11 @@ export function resolveTitle(
 			title = metadata.title;
 		} else {
 			if (typeof metadata.title === "string") {
-				title = titleTemplate.template.split("%s").join(metadata.title);
+				if (typeof titleTemplate.template === "function") {
+					title = titleTemplate.template(metadata.title);
+				} else {
+					title = titleTemplate.template.split("%s").join(metadata.title);
+				}
 			} else {
 				title = titleTemplate.default;
 			}