@devsantara/head 0.2.0 → 0.3.0

package/README.md

@@ -60,7 +60,12 @@ import { HeadBuilder } from '@devsantara/head';
 const head = new HeadBuilder()
   .addTitle('My Awesome Website')
   .addDescription('A comprehensive guide to web development')
+  .addStyle('body { margin: 0; padding: 0; }')
   .addViewport({ width: 'device-width', initialScale: 1 })
+  .addScript({ code: 'console.log("Hello, world!");' })
+  .addScript(new URL('https://devsantara.com/assets/scripts/utils.js'), {
+    async: true,
+  })
   .build();
 ```
 
@@ -85,6 +90,28 @@ const head = new HeadBuilder()
       content: 'width=device-width, initial-scale=1',
     },
   },
+  {
+    type: 'style',
+    attributes: {
+      type: 'text/css',
+      children: 'body { margin: 0; padding: 0; }',
+    },
+  },
+  {
+    type: 'script',
+    attributes: {
+      type: 'text/javascript',
+      children: 'console.log("Hello, world!");',
+    },
+  },
+  {
+    type: 'script',
+    attributes: {
+      type: 'text/javascript',
+      src: 'https://devsantara.com/assets/scripts/utils.js',
+      async: true,
+    },
+  },
 ];
 ```
 
@@ -140,6 +167,95 @@ const head = new HeadBuilder({
 ];
 ```
 
+### With Templated Title
+
+Set a title template with a default value, then pass page-specific titles as strings. The builder automatically applies the saved template to subsequent title updates:
+
+```typescript
+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({
+  template: '%s | My Awesome site', // Store template (%s is the placeholder)
+  default: 'Home', // Initial title using template
+});
+// Output: <title>Home | My Awesome site</title>
+
+// Update title for Posts page
+// Pass a string, builder applies the saved template automatically
+const postHead = sharedHead.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
+3. The `%s` placeholder gets replaced with your page title
+4. Each title replaces the previous one (deduplication)
+
+### With Element Deduplication
+
+HeadBuilder automatically deduplicates elements—when you add an element matching an existing one, the new one replaces the old:
+
+```typescript
+import { HeadBuilder } from '@devsantara/head';
+
+const head = new HeadBuilder()
+  .addTitle('My Site')
+  .addTitle('Updated Title') // Replaces previous title
+
+  .addDescription('First description')
+  .addDescription('Updated description') // Replaces previous
+
+  .addMeta({ name: 'keywords', content: 'web, development' })
+  .addMeta({ name: 'author', content: 'John Doe' }) // Separate meta tags coexist
+
+  .addCanonical('https://devsantara.com/page1')
+  .addCanonical('https://devsantara.com/page2') // Replaces previous canonical
+
+  .build();
+```
+
+```typescript
+// Output (HeadElement[]):
+[
+  { type: 'title', attributes: { children: 'Updated Title' } },
+  {
+    type: 'meta',
+    attributes: { name: 'description', content: 'Updated description' },
+  },
+  {
+    type: 'meta',
+    attributes: { name: 'keywords', content: 'web, development' },
+  },
+  { type: 'meta', attributes: { name: 'author', content: 'John Doe' } },
+  {
+    type: 'link',
+    attributes: { rel: 'canonical', href: 'https://devsantara.com/page2' },
+  },
+];
+```
+
+**How it works:**
+
+- **Title**: Only one per document
+- **Meta by name**: One per unique `name` attribute (e.g., description, keywords)
+- **Meta by property**: One per unique `property` attribute (e.g., `og:title`, `og:description`)
+- **Charset**: Only one per document
+- **Canonical**: Only one per document
+- **Manifest**: Only one per document
+- **Alternate locales**: One per unique language code
+- **Other tags**: Deduplicated by exact attribute match
+
+This ensures clean metadata without accidental duplicates.
+
 ### With React Adapter
 
 ```tsx
@@ -222,13 +338,13 @@ export const Route = createRootRoute({
 
 For advanced use cases not covered by the essential methods below, use these basic methods to add any custom element directly.
 
-| Method                                                  | Description                                      |
-| ------------------------------------------------------- | ------------------------------------------------ |
-| `addTitle(title: string)`                               | Adds a `<title>` element                         |
-| `addMeta(attributes: HeadAttributeTypeMap['meta'])`     | Adds a `<meta>` element with custom attributes   |
-| `addLink(attributes: HeadAttributeTypeMap['link'])`     | Adds a `<link>` element with custom attributes   |
-| `addScript(attributes: HeadAttributeTypeMap['script'])` | Adds a `<script>` element with custom attributes |
-| `addStyle(attributes: HeadAttributeTypeMap['style'])`   | Adds a `<style>` element with custom attributes  |
+| Method                                                                 | Description                                                                                 |
+| ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| `addTitle(title: string \| TitleOptions)`                              | Adds a `<title>` element with optional templating                                           |
+| `addMeta(attributes: HeadAttributeTypeMap['meta'])`                    | Adds a `<meta>` element with custom attributes                                              |
+| `addLink(href: string \| URL, attributes?)`                            | Adds a `<link>` element with a URL and custom attributes                                    |
+| `addScript(srcOrCode: string \| URL \| { code: string }, attributes?)` | Adds a `<script>` element (external file with string/URL or inline with `{ code: string }`) |
+| `addStyle(css: string, attributes?)`                                   | Adds a `<style>` element with inline CSS                                                    |
 
 ### Essential Methods
 

package/dist/adapters/index.d.ts

@@ -1,4 +1,4 @@
-import { c as HeadMetaAttributes, i as HeadAdapter, l as HeadScriptAttributes, o as HeadElement, s as HeadLinkAttributes, u as HeadStyleAttributes } from "../types-Cvpk_Zha.js";
+import { c as HeadMetaAttributes, i as HeadAdapter, l as HeadScriptAttributes, o as HeadElement, s as HeadLinkAttributes, u as HeadStyleAttributes } from "../types-D-ta-0P-.js";
 import { ReactNode } from "react";
 
 //#region src/adapters/react-adapter.d.ts

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { _ as TwitterOptions, a as HeadAttributeTypeMap, c as HeadMetaAttributes, d as HeadTitleAttributes, f as IconOptions, g as StylesheetOptions, h as RobotsOptions, i as HeadAdapter, l as HeadScriptAttributes, m as OpenGraphOptions, n as CharSet, o as HeadElement, p as IconPreset, r as ColorScheme, s as HeadLinkAttributes, t as AlternateLocaleOptions, u as HeadStyleAttributes, v as ViewportOptions } from "./types-Cvpk_Zha.js";
+import { _ as TitleOptions, a as HeadAttributeTypeMap, c as HeadMetaAttributes, d as HeadTitleAttributes, f as IconOptions, g as StylesheetOptions, h as RobotsOptions, i as HeadAdapter, l as HeadScriptAttributes, m as OpenGraphOptions, n as CharSet, o as HeadElement, p as IconPreset, r as ColorScheme, s as HeadLinkAttributes, t as AlternateLocaleOptions, u as HeadStyleAttributes, v as TwitterOptions, y as ViewportOptions } from "./types-D-ta-0P-.js";
 
 //#region src/builder.d.ts
 /**
@@ -18,9 +18,25 @@ interface BuilderHelper {
  */
 type BuilderOption<T> = T | ((helper: BuilderHelper) => T);
 declare class HeadBuilder<TOutput = HeadElement[]> {
+  /**
+   * Optional base URL for resolving relative URLs in metadata (Open Graph, canonical, etc.)
+   */
   private metadataBase?;
-  private elements;
+  /**
+   * Optional adapter to transform the built head elements into a framework-specific format.
+   * If not provided, `build()` returns `HeadElement[]`
+   */
   private adapter?;
+  /**
+   * Internal storage for title options to support templated titles.
+   * This allows the builder to generate the title dynamically based on previously set options.
+   */
+  private titleOptions?;
+  /**
+   * Internal collection of head elements being built,
+   * stored in a Map for deduplication based on element type and key attributes.
+   */
+  private elementsMap;
   /**
    * Resolves a value that can be either static or a callback function receiving helper utilities.
    *
@@ -55,11 +71,20 @@ declare class HeadBuilder<TOutput = HeadElement[]> {
    */
   private resolveUrl;
   /**
-   * Adds a head element to the internal collection for later transformation.
+   * Generates a unique key for a head element based on its type and attributes.
+   * Used for deduplication - elements with the same key replace previous ones.
+   *
+   * @param element - The head element to generate a key for
+   * @returns A unique string key for the element
+   */
+  private getElementKey;
+  /**
+   * Adds a head element to the internal collection with deduplication.
+   * Elements with the same key will replace previous ones.
    *
    * @param type - The HTML element type
    * @param attributes - The element's attributes
-   * @returns The builder instance for method chaining
+   * @returns The unique key for the added element
    */
   private addElement;
   /**
@@ -75,41 +100,48 @@ declare class HeadBuilder<TOutput = HeadElement[]> {
    */
   addMeta(attributes: HeadAttributeTypeMap['meta']): this;
   /**
-   * Adds a custom link element with any valid attributes. Use this for link tags without dedicated helper methods.
+   * Adds a custom link element with any valid attributes.
    *
-   * @param attributes - The link element attributes
+   * @param href - The URL to link to
+   * @param attributes - Additional link element attributes
    * @returns The builder instance for method chaining
    *
    * @example
    * new HeadBuilder()
-   *   .addLink({ rel: 'preconnect', href: 'https://fonts.googleapis.com' })
+   *   .addLink('https://fonts.googleapis.com', { rel: 'preconnect' })
    *   .build();
    */
-  addLink(attributes: HeadAttributeTypeMap['link']): this;
+  addLink(href: string | URL, attributes?: Omit<HeadAttributeTypeMap['link'], 'href'>): this;
   /**
-   * Adds a custom script element with any valid attributes for external scripts or inline code.
+   * Adds a script element, either inline code or an external file.
    *
-   * @param attributes - The script element attributes
+   * @param srcOrCode - Script source: a URL string/object for external files, or `{ code: string }` for inline scripts
+   * @param attributes - Additional script attributes (async, defer, integrity, etc.)
    * @returns The builder instance for method chaining
    *
    * @example
    * new HeadBuilder()
-   *   .addScript({ src: '/analytics.js', async: true })
+   *   .addScript('/script.js')
+   *   .addScript(new URL('https://devsantara.com/script.js'), { async: true })
+   *   .addScript({ code: 'console.log("Hello, World!")' })
    *   .build();
    */
-  addScript(attributes: HeadAttributeTypeMap['script']): this;
+  addScript(srcOrCode: string | URL | {
+    code: string;
+  }, attributes?: Omit<HeadAttributeTypeMap['script'], 'children' | 'src'>): this;
   /**
-   * Adds a custom style element with inline CSS.
+   * Adds an inline style element with CSS code.
    *
-   * @param attributes - The style element attributes
+   * @param css - The inline CSS code
+   * @param attributes - Additional style attributes
    * @returns The builder instance for method chaining
    *
    * @example
    * new HeadBuilder()
-   *   .addStyle({ children: 'body { margin: 0; padding: 0; }' })
+   *   .addStyle('body { margin: 0; padding: 0; }')
    *   .build();
    */
-  addStyle(attributes: HeadAttributeTypeMap['style']): this;
+  addStyle(css: string, attributes?: Omit<HeadAttributeTypeMap['style'], 'children'>): this;
   /**
    * Adds a character encoding declaration to specify how the document should be interpreted.
    *
@@ -136,16 +168,25 @@ declare class HeadBuilder<TOutput = HeadElement[]> {
   addColorScheme(colorScheme: ColorScheme): this;
   /**
    * Adds a title element that appears in browser tabs, search results, and bookmarks.
+   * Supports both simple string titles and templated titles with dynamic substitution.
    *
-   * @param title - The document title text
+   * @param title - The document title as a string, or TitleOptions object with template and default
    * @returns The builder instance for method chaining
    *
    * @example
+   * // Simple title
    * new HeadBuilder()
    *   .addTitle('My Awesome Website')
    *   .build();
+   *
+   * @example
+   * // Templated title with page-specific suffix
+   * const baseHead = new HeadBuilder()
+   *   .addTitle({ template: '%s | My Site', default: 'Home' })
+   *
+   * const head = baseHead.addTitle('About Us').build(); // Results in title "About Us | My Site"
    */
-  addTitle(title: string): this;
+  addTitle(title: string | TitleOptions): this;
   /**
    * Adds viewport configuration for responsive web design and mobile optimization.
    *
@@ -232,7 +273,7 @@ declare class HeadBuilder<TOutput = HeadElement[]> {
    * @returns The builder instance for method chaining
    *
    * @example
-   * new HeadBuilder({ metadataBase: new URL('https://example.com') })
+   * new HeadBuilder({ metadataBase: new URL('https://devsantara.com') })
    *   .addAlternateLocale((helper) => ({
    *     'en-US': helper.resolveUrl('/en'),
    *     'fr-FR': helper.resolveUrl('/fr'),
@@ -290,4 +331,4 @@ declare class HeadBuilder<TOutput = HeadElement[]> {
   build(): TOutput;
 }
 //#endregion
-export { AlternateLocaleOptions, CharSet, ColorScheme, HeadAdapter, HeadAttributeTypeMap, HeadBuilder, HeadElement, HeadLinkAttributes, HeadMetaAttributes, HeadScriptAttributes, HeadStyleAttributes, HeadTitleAttributes, IconOptions, IconPreset, OpenGraphOptions, RobotsOptions, StylesheetOptions, TwitterOptions, ViewportOptions };
+export { AlternateLocaleOptions, CharSet, ColorScheme, HeadAdapter, HeadAttributeTypeMap, HeadBuilder, HeadElement, HeadLinkAttributes, HeadMetaAttributes, HeadScriptAttributes, HeadStyleAttributes, HeadTitleAttributes, IconOptions, IconPreset, OpenGraphOptions, RobotsOptions, StylesheetOptions, TitleOptions, TwitterOptions, ViewportOptions };

package/dist/index.js

@@ -1,9 +1,25 @@
 //#region src/builder.ts
 var HeadBuilder = class {
+	/**
+	* Optional base URL for resolving relative URLs in metadata (Open Graph, canonical, etc.)
+	*/
 	metadataBase;
-	elements = [];
+	/**
+	* Optional adapter to transform the built head elements into a framework-specific format.
+	* If not provided, `build()` returns `HeadElement[]`
+	*/
 	adapter;
 	/**
+	* Internal storage for title options to support templated titles.
+	* This allows the builder to generate the title dynamically based on previously set options.
+	*/
+	titleOptions;
+	/**
+	* Internal collection of head elements being built,
+	* stored in a Map for deduplication based on element type and key attributes.
+	*/
+	elementsMap = /* @__PURE__ */ new Map();
+	/**
 	* Resolves a value that can be either static or a callback function receiving helper utilities.
 	*
 	* @param valueOrFn - Static value or function that returns the value
@@ -41,25 +57,47 @@ var HeadBuilder = class {
 	resolveUrl(url) {
 		if (url instanceof URL) return url.href;
 		if (!this.metadataBase) return url;
-		try {
-			return new URL(url, this.metadataBase).href;
-		} catch {
-			return url;
+		return new URL(url, this.metadataBase).href;
+	}
+	/**
+	* Generates a unique key for a head element based on its type and attributes.
+	* Used for deduplication - elements with the same key replace previous ones.
+	*
+	* @param element - The head element to generate a key for
+	* @returns A unique string key for the element
+	*/
+	getElementKey({ type, attributes }) {
+		if (type === "title") return "title";
+		if (type === "meta") {
+			if ("charSet" in attributes) return "meta:charSet";
+			if ("name" in attributes && "content" in attributes) return `meta:name:${attributes.name}`;
+			if ("property" in attributes && "content" in attributes) return `meta:property:${attributes.property}`;
+		}
+		if (type === "link") {
+			if (attributes.rel === "canonical") return "link:canonical";
+			if (attributes.rel === "manifest") return "link:manifest";
+			if (attributes.rel === "alternate" && "hrefLang" in attributes) return `link:alternate:${attributes.hrefLang}`;
 		}
+		return JSON.stringify(`${type}:${JSON.stringify(attributes)}`);
 	}
 	/**
-	* Adds a head element to the internal collection for later transformation.
+	* Adds a head element to the internal collection with deduplication.
+	* Elements with the same key will replace previous ones.
 	*
 	* @param type - The HTML element type
 	* @param attributes - The element's attributes
-	* @returns The builder instance for method chaining
+	* @returns The unique key for the added element
 	*/
 	addElement(type, attributes) {
-		this.elements.push({
+		const key = this.getElementKey({
 			type,
 			attributes
 		});
-		return this;
+		this.elementsMap.set(key, {
+			type,
+			attributes
+		});
+		return key;
 	}
 	/**
 	* Adds a custom meta element with any valid attributes. Use this for meta tags without dedicated helper methods.
@@ -73,49 +111,77 @@ var HeadBuilder = class {
 	*   .build();
 	*/
 	addMeta(attributes) {
-		return this.addElement("meta", attributes);
+		this.addElement("meta", attributes);
+		return this;
 	}
 	/**
-	* Adds a custom link element with any valid attributes. Use this for link tags without dedicated helper methods.
+	* Adds a custom link element with any valid attributes.
 	*
-	* @param attributes - The link element attributes
+	* @param href - The URL to link to
+	* @param attributes - Additional link element attributes
 	* @returns The builder instance for method chaining
 	*
 	* @example
 	* new HeadBuilder()
-	*   .addLink({ rel: 'preconnect', href: 'https://fonts.googleapis.com' })
+	*   .addLink('https://fonts.googleapis.com', { rel: 'preconnect' })
 	*   .build();
 	*/
-	addLink(attributes) {
-		return this.addElement("link", attributes);
+	addLink(href, attributes) {
+		this.addElement("link", {
+			href: href.toString(),
+			...attributes
+		});
+		return this;
 	}
 	/**
-	* Adds a custom script element with any valid attributes for external scripts or inline code.
+	* Adds a script element, either inline code or an external file.
 	*
-	* @param attributes - The script element attributes
+	* @param srcOrCode - Script source: a URL string/object for external files, or `{ code: string }` for inline scripts
+	* @param attributes - Additional script attributes (async, defer, integrity, etc.)
 	* @returns The builder instance for method chaining
 	*
 	* @example
 	* new HeadBuilder()
-	*   .addScript({ src: '/analytics.js', async: true })
+	*   .addScript('/script.js')
+	*   .addScript(new URL('https://devsantara.com/script.js'), { async: true })
+	*   .addScript({ code: 'console.log("Hello, World!")' })
 	*   .build();
 	*/
-	addScript(attributes) {
-		return this.addElement("script", attributes);
+	addScript(srcOrCode, attributes) {
+		if (typeof srcOrCode === "object" && "code" in srcOrCode) {
+			this.addElement("script", {
+				children: srcOrCode.code,
+				type: "text/javascript",
+				...attributes
+			});
+			return this;
+		}
+		this.addElement("script", {
+			src: srcOrCode.toString(),
+			type: "text/javascript",
+			...attributes
+		});
+		return this;
 	}
 	/**
-	* Adds a custom style element with inline CSS.
+	* Adds an inline style element with CSS code.
 	*
-	* @param attributes - The style element attributes
+	* @param css - The inline CSS code
+	* @param attributes - Additional style attributes
 	* @returns The builder instance for method chaining
 	*
 	* @example
 	* new HeadBuilder()
-	*   .addStyle({ children: 'body { margin: 0; padding: 0; }' })
+	*   .addStyle('body { margin: 0; padding: 0; }')
 	*   .build();
 	*/
-	addStyle(attributes) {
-		return this.addElement("style", attributes);
+	addStyle(css, attributes) {
+		this.addElement("style", {
+			children: css,
+			type: "text/css",
+			...attributes
+		});
+		return this;
 	}
 	/**
 	* Adds a character encoding declaration to specify how the document should be interpreted.
@@ -129,7 +195,8 @@ var HeadBuilder = class {
 	*   .build();
 	*/
 	addCharSet(charSet) {
-		return this.addElement("meta", { charSet });
+		this.addElement("meta", { charSet });
+		return this;
 	}
 	/**
 	* Adds a color scheme preference indicating which color schemes the page supports for proper rendering.
@@ -143,24 +210,50 @@ var HeadBuilder = class {
 	*   .build();
 	*/
 	addColorScheme(colorScheme) {
-		return this.addElement("meta", {
+		this.addElement("meta", {
 			name: "color-scheme",
 			content: colorScheme
 		});
+		return this;
 	}
 	/**
 	* Adds a title element that appears in browser tabs, search results, and bookmarks.
+	* Supports both simple string titles and templated titles with dynamic substitution.
 	*
-	* @param title - The document title text
+	* @param title - The document title as a string, or TitleOptions object with template and default
 	* @returns The builder instance for method chaining
 	*
 	* @example
+	* // Simple title
 	* new HeadBuilder()
 	*   .addTitle('My Awesome Website')
 	*   .build();
+	*
+	* @example
+	* // Templated title with page-specific suffix
+	* const baseHead = new HeadBuilder()
+	*   .addTitle({ template: '%s | My Site', default: 'Home' })
+	*
+	* const head = baseHead.addTitle('About Us').build(); // Results in title "About Us | My Site"
 	*/
 	addTitle(title) {
-		return this.addElement("title", { children: title });
+		if (typeof title === "string") {
+			/**
+			* If title is provided as a string and titleOptions with a template exists,
+			* we generate the title using the template. This allows dynamic title generation based on previously set options.
+			* If no template is set, we use the raw title string as is.
+			*/
+			const titleText = this.titleOptions ? this.titleOptions.template.replace("%s", title) : title;
+			this.addElement("title", { children: titleText });
+			return this;
+		}
+		/**
+		* If title is provided as an object with template and default,
+		* we store the options and generate the title using the template with default.
+		*/
+		this.titleOptions = title;
+		this.addElement("title", { children: this.titleOptions.template.replace("%s", title.default) });
+		return this;
 	}
 	/**
 	* Adds viewport configuration for responsive web design and mobile optimization.
@@ -183,10 +276,11 @@ var HeadBuilder = class {
 		if (options.userScalable !== void 0) contentParts.push(`user-scalable=${options.userScalable ? "yes" : "no"}`);
 		if (options.viewportFit !== void 0) contentParts.push(`viewport-fit=${options.viewportFit}`);
 		if (options.interactiveWidget !== void 0) contentParts.push(`interactive-widget=${options.interactiveWidget}`);
-		return this.addElement("meta", {
+		this.addElement("meta", {
 			name: "viewport",
 			content: contentParts.join(", ")
 		});
+		return this;
 	}
 	/**
 	* Adds a description that appears in search engine results and social media previews.
@@ -200,10 +294,11 @@ var HeadBuilder = class {
 	*   .build();
 	*/
 	addDescription(description) {
-		return this.addElement("meta", {
+		this.addElement("meta", {
 			name: "description",
 			content: description
 		});
+		return this;
 	}
 	/**
 	* Adds a canonical URL to help search engines identify the preferred version of a page and prevent duplicate content issues.
@@ -218,10 +313,11 @@ var HeadBuilder = class {
 	*/
 	addCanonical(valueOrFn) {
 		const value = this.parseValueOrFn(valueOrFn);
-		return this.addElement("link", {
+		this.addElement("link", {
 			rel: "canonical",
 			href: value.toString()
 		});
+		return this;
 	}
 	/**
 	* Adds robots directives to control search engine crawling and indexing behavior.
@@ -243,10 +339,11 @@ var HeadBuilder = class {
 			else if (typeof value === "string" || typeof value === "number") directiveParts.push(`${key}:${value}`);
 			else if (value) directiveParts.push(key);
 		}
-		return this.addElement("meta", {
+		this.addElement("meta", {
 			name: "robots",
 			content: directiveParts.join(", ")
 		});
+		return this;
 	}
 	/**
 	* Adds Open Graph metadata for rich social media previews on platforms like Facebook, LinkedIn, and Slack.
@@ -264,51 +361,51 @@ var HeadBuilder = class {
 	*   .build();
 	*/
 	addOpenGraph(valueOrFn) {
-		const options = this.parseValueOrFn(valueOrFn);
-		if (options.title) this.addElement("meta", {
+		const value = this.parseValueOrFn(valueOrFn);
+		if (value.title) this.addElement("meta", {
 			property: "og:title",
-			content: options.title
+			content: value.title
 		});
-		if (options.description) this.addElement("meta", {
+		if (value.description) this.addElement("meta", {
 			property: "og:description",
-			content: options.description
+			content: value.description
 		});
-		if (options.url) this.addElement("meta", {
+		if (value.url) this.addElement("meta", {
 			property: "og:url",
-			content: options.url.toString()
+			content: value.url.toString()
 		});
-		if (options.locale) this.addElement("meta", {
+		if (value.locale) this.addElement("meta", {
 			property: "og:locale",
-			content: options.locale
+			content: value.locale
 		});
-		if (options.image) {
+		if (value.image) {
 			this.addElement("meta", {
 				property: "og:image",
-				content: options.image.url.toString()
+				content: value.image.url.toString()
 			});
-			if (options.image.alt) this.addElement("meta", {
+			if (value.image.alt) this.addElement("meta", {
 				property: "og:image:alt",
-				content: options.image.alt
+				content: value.image.alt
 			});
-			if (options.image.type) this.addElement("meta", {
+			if (value.image.type) this.addElement("meta", {
 				property: "og:image:type",
-				content: options.image.type
+				content: value.image.type
 			});
-			if (options.image.width) this.addElement("meta", {
+			if (value.image.width) this.addElement("meta", {
 				property: "og:image:width",
-				content: options.image.width.toString()
+				content: value.image.width.toString()
 			});
-			if (options.image.height) this.addElement("meta", {
+			if (value.image.height) this.addElement("meta", {
 				property: "og:image:height",
-				content: options.image.height.toString()
+				content: value.image.height.toString()
 			});
 		}
-		if (options.type) {
+		if (value.type) {
 			this.addElement("meta", {
 				property: "og:type",
-				content: options.type.name
+				content: value.type.name
 			});
-			if ("properties" in options.type) for (const typeProperty of options.type.properties) this.addElement("meta", {
+			if ("properties" in value.type) for (const typeProperty of value.type.properties) this.addElement("meta", {
 				property: typeProperty.name,
 				content: typeProperty.content
 			});
@@ -330,47 +427,47 @@ var HeadBuilder = class {
 	*   .build();
 	*/
 	addTwitter(valueOrFn) {
-		const options = this.parseValueOrFn(valueOrFn);
-		if (options.title) this.addElement("meta", {
+		const value = this.parseValueOrFn(valueOrFn);
+		if (value.title) this.addElement("meta", {
 			name: "twitter:title",
-			content: options.title
+			content: value.title
 		});
-		if (options.description) this.addElement("meta", {
+		if (value.description) this.addElement("meta", {
 			name: "twitter:description",
-			content: options.description
+			content: value.description
 		});
-		if (options.site) this.addElement("meta", {
+		if (value.site) this.addElement("meta", {
 			name: "twitter:site",
-			content: options.site
+			content: value.site
 		});
-		if (options.siteId) this.addElement("meta", {
+		if (value.siteId) this.addElement("meta", {
 			name: "twitter:site:id",
-			content: options.siteId
+			content: value.siteId
 		});
-		if (options.creator) this.addElement("meta", {
+		if (value.creator) this.addElement("meta", {
 			name: "twitter:creator",
-			content: options.creator
+			content: value.creator
 		});
-		if (options.creatorId) this.addElement("meta", {
+		if (value.creatorId) this.addElement("meta", {
 			name: "twitter:creator:id",
-			content: options.creatorId
+			content: value.creatorId
 		});
-		if (options.image) {
+		if (value.image) {
 			this.addElement("meta", {
 				name: "twitter:image",
-				content: options.image.url.toString()
+				content: value.image.url.toString()
 			});
-			if (options.image.alt) this.addElement("meta", {
+			if (value.image.alt) this.addElement("meta", {
 				name: "twitter:image:alt",
-				content: options.image.alt
+				content: value.image.alt
 			});
 		}
-		if (options.card) {
+		if (value.card) {
 			this.addElement("meta", {
 				name: "twitter:card",
-				content: options.card.name
+				content: value.card.name
 			});
-			if ("properties" in options.card) for (const cardProperty of options.card.properties) this.addElement("meta", {
+			if ("properties" in value.card) for (const cardProperty of value.card.properties) this.addElement("meta", {
 				name: cardProperty.name,
 				content: cardProperty.content.toString()
 			});
@@ -384,7 +481,7 @@ var HeadBuilder = class {
 	* @returns The builder instance for method chaining
 	*
 	* @example
-	* new HeadBuilder({ metadataBase: new URL('https://example.com') })
+	* new HeadBuilder({ metadataBase: new URL('https://devsantara.com') })
 	*   .addAlternateLocale((helper) => ({
 	*     'en-US': helper.resolveUrl('/en'),
 	*     'fr-FR': helper.resolveUrl('/fr'),
@@ -393,8 +490,8 @@ var HeadBuilder = class {
 	*   .build();
 	*/
 	addAlternateLocale(valueOrFn) {
-		const options = this.parseValueOrFn(valueOrFn);
-		for (const [lang, href] of Object.entries(options)) this.addElement("link", {
+		const value = this.parseValueOrFn(valueOrFn);
+		for (const [lang, href] of Object.entries(value)) this.addElement("link", {
 			rel: "alternate",
 			hrefLang: lang,
 			href: String(href)
@@ -413,11 +510,12 @@ var HeadBuilder = class {
 	*   .build();
 	*/
 	addManifest(valueOrFn) {
-		const href = this.parseValueOrFn(valueOrFn);
-		return this.addElement("link", {
+		const value = this.parseValueOrFn(valueOrFn);
+		this.addElement("link", {
 			rel: "manifest",
-			href: href.toString()
+			href: value.toString()
 		});
+		return this;
 	}
 	/**
 	* Adds an external CSS stylesheet link to the page.
@@ -432,11 +530,13 @@ var HeadBuilder = class {
 	*   .build();
 	*/
 	addStylesheet(href, options) {
-		return this.addElement("link", {
+		this.addElement("link", {
 			rel: "stylesheet",
+			type: "text/css",
 			href: href.toString(),
 			...options
 		});
+		return this;
 	}
 	/**
 	* Adds a favicon or app icon using preset types or custom rel values.
@@ -454,20 +554,18 @@ var HeadBuilder = class {
 	*   .build();
 	*/
 	addIcon(preset, valueOrFn) {
-		const options = this.parseValueOrFn(valueOrFn);
+		const { href, ...value } = this.parseValueOrFn(valueOrFn);
 		const rel = {
 			apple: "apple-touch-icon",
 			icon: "icon",
 			shortcut: "shortcut icon"
 		}[preset] || preset;
-		return this.addElement("link", {
+		this.addElement("link", {
 			rel,
-			href: options.href.toString(),
-			type: options.type,
-			sizes: options.sizes,
-			media: options.media,
-			fetchPriority: options.fetchPriority
+			href: href.toString(),
+			...value
 		});
+		return this;
 	}
 	/**
 	* Builds and returns the final head configuration. Returns adapted output if an adapter was provided, otherwise returns `HeadElement[]`.
@@ -475,8 +573,9 @@ var HeadBuilder = class {
 	* @returns The head configuration in the target format
 	*/
 	build() {
-		if (this.adapter) return this.adapter.transform(this.elements);
-		return this.elements;
+		const elements = Array.from(this.elementsMap.values());
+		if (this.adapter) return this.adapter.transform(elements);
+		return elements;
 	}
 };
 

package/dist/{types-Cvpk_Zha.d.ts → types-D-ta-0P-.d.ts}

@@ -54,6 +54,13 @@ type CharSet = 'utf-8' | (string & {});
  * Color scheme preference indicating which color schemes the document supports.
  */
 type ColorScheme = 'light' | 'dark' | 'light dark' | 'dark light' | 'only light' | 'only dark' | 'normal' | (string & {});
+/**
+ * Title configuration with support for templated titles using a template string and default title value.
+ */
+type TitleOptions = {
+  template: string;
+  default: string;
+};
 /**
  * Viewport configuration for responsive web design and mobile optimization.
  */
@@ -430,13 +437,16 @@ interface TwitterOptions {
   card?: TwitterCard;
 }
 /**
- * Locale key type supporting 'x-default', specific locale strings, or custom values.
+ * Locale key type supporting specific locale strings or custom values.
  */
-type AlternateLocaleKey<TLocale extends string> = ('x-default' | TLocale) | (string & {});
+type AlternateLocaleKey<TLocale extends string> = TLocale | (string & {});
 /**
  * Alternate locale/language mapping for internationalization, linking language codes to their corresponding URLs.
+ * The 'x-default' key is optional.
  */
-type AlternateLocaleOptions<TLocale extends string> = Record<AlternateLocaleKey<TLocale>, string | URL>;
+type AlternateLocaleOptions<TLocale extends string> = {
+  'x-default'?: string | URL;
+} & Record<AlternateLocaleKey<TLocale>, string | URL>;
 /**
  * Icon preset type with autocomplete for common icon types while allowing custom values.
  */
@@ -452,4 +462,4 @@ type IconOptions = Omit<HeadAttributeTypeMap['link'], 'rel' | 'href'> & {
  */
 type StylesheetOptions = Omit<HeadLinkAttributes, 'rel' | 'href'>;
 //#endregion
-export { TwitterOptions as _, HeadAttributeTypeMap as a, HeadMetaAttributes as c, HeadTitleAttributes as d, IconOptions as f, StylesheetOptions as g, RobotsOptions as h, HeadAdapter as i, HeadScriptAttributes as l, OpenGraphOptions as m, CharSet as n, HeadElement as o, IconPreset as p, ColorScheme as r, HeadLinkAttributes as s, AlternateLocaleOptions as t, HeadStyleAttributes as u, ViewportOptions as v };
+export { TitleOptions as _, HeadAttributeTypeMap as a, HeadMetaAttributes as c, HeadTitleAttributes as d, IconOptions as f, StylesheetOptions as g, RobotsOptions as h, HeadAdapter as i, HeadScriptAttributes as l, OpenGraphOptions as m, CharSet as n, HeadElement as o, IconPreset as p, ColorScheme as r, HeadLinkAttributes as s, AlternateLocaleOptions as t, HeadStyleAttributes as u, TwitterOptions as v, ViewportOptions as y };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devsantara/head",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "A type-safe HTML head builder",
   "keywords": [
     "devsantara",
@@ -35,6 +35,8 @@
   },
   "devDependencies": {
     "@changesets/cli": "^2.29.8",
+    "@vitest/coverage-v8": "4.0.18",
+    "@vitest/ui": "4.0.18",
     "oxfmt": "^0.27.0",
     "oxlint": "^1.42.0",
     "oxlint-tsgolint": "^0.11.4",
@@ -50,6 +52,8 @@
     "build": "tsdown",
     "dev": "tsdown --watch",
     "test": "vitest",
+    "test:ui": "vitest --ui",
+    "test:coverage": "vitest run --coverage",
     "lint": "oxlint --type-aware",
     "lint:fix": "oxlint --type-aware --fix",
     "lint:ts": "tsc --noEmit",