Release v0.4.1

Author: edwintantawi

.changeset/famous-ideas-share.md

@@ -0,0 +1,5 @@
+---
+'@devsantara/head': patch
+---
+
+fix(add-title): default title should show without the template

README.md

@@ -176,28 +176,23 @@ Set a title template with a default value, then pass page-specific titles as str
 import { HeadBuilder } from '@devsantara/head';
 
 // Create a builder and set title template with default
-// The template stays active for all future addTitle() calls
-const sharedHead = new HeadBuilder().addTitle({
+// The default value is used initially, template is stored for future use
+const baseHead = new HeadBuilder().addTitle({
   template: '%s | My Awesome site', // Store template (%s is the placeholder)
-  default: 'Home', // Initial title using template
+  default: 'Home', // Initial title (template not applied yet)
 });
-// Output: <title>Home | My Awesome site</title>
+// Output: <title>Home</title>
 
 // Update title for Posts page
 // Pass a string, builder applies the saved template automatically
-const postHead = sharedHead.addTitle('Posts').build();
+const postHead = baseHead.addTitle('Posts').build();
 // Output: <title>Posts | My Awesome site</title>
-
-// Update title for About page
-// Template is still active from the first addTitle() call
-const aboutHead = sharedHead.addTitle('About Us').build();
-// Output: <title>About Us | My Awesome site</title>
 ```
 
 **How it works:**
 
-1. First `addTitle()` with template object stores the template internally
-2. Subsequent `addTitle()` calls with strings automatically use the stored template
+1. First `addTitle()` with template object stores the template internally and uses just the default value
+2. Subsequent `addTitle()` calls with strings automatically apply the stored template
 3. The `%s` placeholder gets replaced with your page title
 4. Each title replaces the previous one (deduplication)
 

src/builder.ts

@@ -327,6 +327,8 @@ export class HeadBuilder<TOutput = HeadElement[]> {
    * Adds a title element that appears in browser tabs, search results, and bookmarks.
    * Supports both simple string titles and templated titles with dynamic substitution.
    *
+   * When a template is provided via TitleOptions, the default is used initially and the template is applied to subsequent string titles.
+   *
    * @param title - The document title as a string, or TitleOptions object with template and default
    * @returns The builder instance for method chaining
    *
@@ -338,9 +340,11 @@ export class HeadBuilder<TOutput = HeadElement[]> {
    *
    * @example
    * // Templated title with page-specific suffix
+   * // Setting the template with default stores 'Home' as the title
    * const baseHead = new HeadBuilder()
-   *   .addTitle({ template: '%s | My Site', default: 'Home' })
+   *   .addTitle({ template: '%s | My Site', default: 'Home' });
    *
+   * // Subsequent string titles apply the template
    * const head = baseHead.addTitle('About Us').build(); // Results in title "About Us | My Site"
    */
   addTitle(title: string | TitleOptions): this {
@@ -360,12 +364,10 @@ export class HeadBuilder<TOutput = HeadElement[]> {
 
     /**
      * If title is provided as an object with template and default,
-     * we store the options and generate the title using the template with default.
+     * we store the options and add the default title. Subsequent calls with string titles will use the template for generation.
      */
     this.titleOptions = title;
-    this.addElement('title', {
-      children: this.titleOptions.template.replace('%s', title.default),
-    });
+    this.addElement('title', { children: this.titleOptions.default });
     return this;
   }
 

src/tests/builder-add-title.test.ts

@@ -19,7 +19,7 @@ describe('HeadBuilder.addTitle', () => {
 
     expect(result[0]).toEqual({
       type: 'title',
-      attributes: { children: 'Home | My Site' },
+      attributes: { children: 'Home' },
     });
   });
 
@@ -36,15 +36,28 @@ describe('HeadBuilder.addTitle', () => {
     });
   });
 
-  it('should update template when new template is set', () => {
+  it('should update template when new template is set (default template)', () => {
     const result = new HeadBuilder()
       .addTitle({ template: '%s | Site A', default: 'Home' })
       .addTitle({ template: '%s | Site B', default: 'Index' })
       .build();
 
     expect(result[0]).toEqual({
       type: 'title',
-      attributes: { children: 'Index | Site B' },
+      attributes: { children: 'Index' },
+    });
+  });
+
+  it('should update template when new template is set (full template)', () => {
+    const result = new HeadBuilder()
+      .addTitle({ template: '%s | Site A', default: 'Home' })
+      .addTitle({ template: '%s | Site B', default: 'Index' })
+      .addTitle('Contact')
+      .build();
+
+    expect(result[0]).toEqual({
+      type: 'title',
+      attributes: { children: 'Contact | Site B' },
     });
   });