@devsantara/head 0.2.0

package/dist/index.js

@@ -0,0 +1,484 @@
+//#region src/builder.ts
+var HeadBuilder = class {
+	metadataBase;
+	elements = [];
+	adapter;
+	/**
+	* 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
+	* @returns The resolved value
+	*/
+	parseValueOrFn(valueOrFn) {
+		if (typeof valueOrFn === "function") return valueOrFn({ resolveUrl: this.resolveUrl.bind(this) });
+		return valueOrFn;
+	}
+	/**
+	* Creates a new HeadBuilder instance for constructing HTML head elements with optional base URL resolution and output transformation.
+	*
+	* @param options - Configuration options
+	* @param options.metadataBase - Base URL for resolving relative URLs in metadata (Open Graph, canonical, etc.)
+	* @param options.adapter - Adapter to transform output into framework-specific format
+	*
+	* @example
+	* const head = new HeadBuilder({
+	*   metadataBase: new URL('https://devsantara.com'),
+	*   adapter: new ReactAdapter()
+	* })
+	*   .addTitle('My Site')
+	*   .build();
+	*/
+	constructor(options) {
+		this.metadataBase = options?.metadataBase;
+		this.adapter = options?.adapter;
+	}
+	/**
+	* Resolves a relative or absolute URL into an absolute URL using the configured metadataBase.
+	*
+	* @param url - The URL to resolve
+	* @returns The resolved absolute URL as a string
+	*/
+	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;
+		}
+	}
+	/**
+	* Adds a head element to the internal collection for later transformation.
+	*
+	* @param type - The HTML element type
+	* @param attributes - The element's attributes
+	* @returns The builder instance for method chaining
+	*/
+	addElement(type, attributes) {
+		this.elements.push({
+			type,
+			attributes
+		});
+		return this;
+	}
+	/**
+	* Adds a custom meta element with any valid attributes. Use this for meta tags without dedicated helper methods.
+	*
+	* @param attributes - The meta element attributes
+	* @returns The builder instance for method chaining
+	*
+	* @example
+	* new HeadBuilder()
+	*   .addMeta({ name: 'theme-color', content: '#ffffff' })
+	*   .build();
+	*/
+	addMeta(attributes) {
+		return this.addElement("meta", attributes);
+	}
+	/**
+	* Adds a custom link element with any valid attributes. Use this for link tags without dedicated helper methods.
+	*
+	* @param attributes - The link element attributes
+	* @returns The builder instance for method chaining
+	*
+	* @example
+	* new HeadBuilder()
+	*   .addLink({ rel: 'preconnect', href: 'https://fonts.googleapis.com' })
+	*   .build();
+	*/
+	addLink(attributes) {
+		return this.addElement("link", attributes);
+	}
+	/**
+	* Adds a custom script element with any valid attributes for external scripts or inline code.
+	*
+	* @param attributes - The script element attributes
+	* @returns The builder instance for method chaining
+	*
+	* @example
+	* new HeadBuilder()
+	*   .addScript({ src: '/analytics.js', async: true })
+	*   .build();
+	*/
+	addScript(attributes) {
+		return this.addElement("script", attributes);
+	}
+	/**
+	* Adds a custom style element with inline CSS.
+	*
+	* @param attributes - The style element attributes
+	* @returns The builder instance for method chaining
+	*
+	* @example
+	* new HeadBuilder()
+	*   .addStyle({ children: 'body { margin: 0; padding: 0; }' })
+	*   .build();
+	*/
+	addStyle(attributes) {
+		return this.addElement("style", attributes);
+	}
+	/**
+	* Adds a character encoding declaration to specify how the document should be interpreted.
+	*
+	* @param charSet - The character encoding (e.g., 'utf-8', 'iso-8859-1')
+	* @returns The builder instance for method chaining
+	*
+	* @example
+	* new HeadBuilder()
+	*   .addCharSet('utf-8')
+	*   .build();
+	*/
+	addCharSet(charSet) {
+		return this.addElement("meta", { charSet });
+	}
+	/**
+	* Adds a color scheme preference indicating which color schemes the page supports for proper rendering.
+	*
+	* @param colorScheme - The supported color schemes (e.g., 'light', 'dark', 'light dark')
+	* @returns The builder instance for method chaining
+	*
+	* @example
+	* new HeadBuilder()
+	*   .addColorScheme('light dark')
+	*   .build();
+	*/
+	addColorScheme(colorScheme) {
+		return this.addElement("meta", {
+			name: "color-scheme",
+			content: colorScheme
+		});
+	}
+	/**
+	* Adds a title element that appears in browser tabs, search results, and bookmarks.
+	*
+	* @param title - The document title text
+	* @returns The builder instance for method chaining
+	*
+	* @example
+	* new HeadBuilder()
+	*   .addTitle('My Awesome Website')
+	*   .build();
+	*/
+	addTitle(title) {
+		return this.addElement("title", { children: title });
+	}
+	/**
+	* Adds viewport configuration for responsive web design and mobile optimization.
+	*
+	* @param options - Viewport settings (width, initial scale, zoom controls, etc.)
+	* @returns The builder instance for method chaining
+	*
+	* @example
+	* new HeadBuilder()
+	*   .addViewport({ width: 'device-width', initialScale: 1 })
+	*   .build();
+	*/
+	addViewport(options) {
+		const contentParts = [];
+		if (options.width !== void 0) contentParts.push(`width=${options.width}`);
+		if (options.height !== void 0) contentParts.push(`height=${options.height}`);
+		if (options.initialScale !== void 0) contentParts.push(`initial-scale=${options.initialScale}`);
+		if (options.minimumScale !== void 0) contentParts.push(`minimum-scale=${options.minimumScale}`);
+		if (options.maximumScale !== void 0) contentParts.push(`maximum-scale=${options.maximumScale}`);
+		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", {
+			name: "viewport",
+			content: contentParts.join(", ")
+		});
+	}
+	/**
+	* Adds a description that appears in search engine results and social media previews.
+	*
+	* @param description - The page description text
+	* @returns The builder instance for method chaining
+	*
+	* @example
+	* new HeadBuilder()
+	*   .addDescription('A comprehensive guide to web development')
+	*   .build();
+	*/
+	addDescription(description) {
+		return this.addElement("meta", {
+			name: "description",
+			content: description
+		});
+	}
+	/**
+	* Adds a canonical URL to help search engines identify the preferred version of a page and prevent duplicate content issues.
+	*
+	* @param valueOrFn - The canonical URL or a callback function receiving helper utilities
+	* @returns The builder instance for method chaining
+	*
+	* @example
+	* new HeadBuilder({ metadataBase: new URL('https://devsantara.com') })
+	*   .addCanonical((helper) => helper.resolveUrl('/page'))
+	*   .build();
+	*/
+	addCanonical(valueOrFn) {
+		const value = this.parseValueOrFn(valueOrFn);
+		return this.addElement("link", {
+			rel: "canonical",
+			href: value.toString()
+		});
+	}
+	/**
+	* Adds robots directives to control search engine crawling and indexing behavior.
+	*
+	* @param options - Robots configuration with index/follow booleans and custom directives
+	* @returns The builder instance for method chaining
+	*
+	* @example
+	* new HeadBuilder()
+	*   .addRobots({ index: true, follow: true, 'max-snippet': 160 })
+	*   .build();
+	*/
+	addRobots(options) {
+		const directiveParts = [];
+		for (const [key, value] of Object.entries(options)) {
+			if (value === void 0) continue;
+			if (key === "index") directiveParts.push(value ? "index" : "noindex");
+			else if (key === "follow") directiveParts.push(value ? "follow" : "nofollow");
+			else if (typeof value === "string" || typeof value === "number") directiveParts.push(`${key}:${value}`);
+			else if (value) directiveParts.push(key);
+		}
+		return this.addElement("meta", {
+			name: "robots",
+			content: directiveParts.join(", ")
+		});
+	}
+	/**
+	* Adds Open Graph metadata for rich social media previews on platforms like Facebook, LinkedIn, and Slack.
+	*
+	* @param valueOrFn - Open Graph configuration or a callback function receiving helper utilities
+	* @returns The builder instance for method chaining
+	*
+	* @example
+	* new HeadBuilder({ metadataBase: new URL('https://devsantara.com') })
+	*   .addOpenGraph((helper) => ({
+	*     title: 'My Page',
+	*     url: helper.resolveUrl('/page'),
+	*     image: { url: helper.resolveUrl('/og-image.jpg') }
+	*   }))
+	*   .build();
+	*/
+	addOpenGraph(valueOrFn) {
+		const options = this.parseValueOrFn(valueOrFn);
+		if (options.title) this.addElement("meta", {
+			property: "og:title",
+			content: options.title
+		});
+		if (options.description) this.addElement("meta", {
+			property: "og:description",
+			content: options.description
+		});
+		if (options.url) this.addElement("meta", {
+			property: "og:url",
+			content: options.url.toString()
+		});
+		if (options.locale) this.addElement("meta", {
+			property: "og:locale",
+			content: options.locale
+		});
+		if (options.image) {
+			this.addElement("meta", {
+				property: "og:image",
+				content: options.image.url.toString()
+			});
+			if (options.image.alt) this.addElement("meta", {
+				property: "og:image:alt",
+				content: options.image.alt
+			});
+			if (options.image.type) this.addElement("meta", {
+				property: "og:image:type",
+				content: options.image.type
+			});
+			if (options.image.width) this.addElement("meta", {
+				property: "og:image:width",
+				content: options.image.width.toString()
+			});
+			if (options.image.height) this.addElement("meta", {
+				property: "og:image:height",
+				content: options.image.height.toString()
+			});
+		}
+		if (options.type) {
+			this.addElement("meta", {
+				property: "og:type",
+				content: options.type.name
+			});
+			if ("properties" in options.type) for (const typeProperty of options.type.properties) this.addElement("meta", {
+				property: typeProperty.name,
+				content: typeProperty.content
+			});
+		}
+		return this;
+	}
+	/**
+	* Adds Twitter Card metadata for rich previews when links are shared on Twitter/X.
+	*
+	* @param valueOrFn - Twitter Card configuration or a callback function receiving helper utilities
+	* @returns The builder instance for method chaining
+	*
+	* @example
+	* new HeadBuilder({ metadataBase: new URL('https://devsantara.com') })
+	*   .addTwitter((helper) => ({
+	*     card: { name: 'summary_large_image' },
+	*     image: { url: helper.resolveUrl('/twitter-card.jpg') }
+	*   }))
+	*   .build();
+	*/
+	addTwitter(valueOrFn) {
+		const options = this.parseValueOrFn(valueOrFn);
+		if (options.title) this.addElement("meta", {
+			name: "twitter:title",
+			content: options.title
+		});
+		if (options.description) this.addElement("meta", {
+			name: "twitter:description",
+			content: options.description
+		});
+		if (options.site) this.addElement("meta", {
+			name: "twitter:site",
+			content: options.site
+		});
+		if (options.siteId) this.addElement("meta", {
+			name: "twitter:site:id",
+			content: options.siteId
+		});
+		if (options.creator) this.addElement("meta", {
+			name: "twitter:creator",
+			content: options.creator
+		});
+		if (options.creatorId) this.addElement("meta", {
+			name: "twitter:creator:id",
+			content: options.creatorId
+		});
+		if (options.image) {
+			this.addElement("meta", {
+				name: "twitter:image",
+				content: options.image.url.toString()
+			});
+			if (options.image.alt) this.addElement("meta", {
+				name: "twitter:image:alt",
+				content: options.image.alt
+			});
+		}
+		if (options.card) {
+			this.addElement("meta", {
+				name: "twitter:card",
+				content: options.card.name
+			});
+			if ("properties" in options.card) for (const cardProperty of options.card.properties) this.addElement("meta", {
+				name: cardProperty.name,
+				content: cardProperty.content.toString()
+			});
+		}
+		return this;
+	}
+	/**
+	* Adds alternate language/locale versions of the page to help search engines serve the correct localized content to users.
+	*
+	* @param valueOrFn - Locale-to-URL mapping or a callback function receiving helper utilities
+	* @returns The builder instance for method chaining
+	*
+	* @example
+	* new HeadBuilder({ metadataBase: new URL('https://example.com') })
+	*   .addAlternateLocale((helper) => ({
+	*     'en-US': helper.resolveUrl('/en'),
+	*     'fr-FR': helper.resolveUrl('/fr'),
+	*     'x-default': helper.resolveUrl('/')
+	*   }))
+	*   .build();
+	*/
+	addAlternateLocale(valueOrFn) {
+		const options = this.parseValueOrFn(valueOrFn);
+		for (const [lang, href] of Object.entries(options)) this.addElement("link", {
+			rel: "alternate",
+			hrefLang: lang,
+			href: String(href)
+		});
+		return this;
+	}
+	/**
+	* Adds a web app manifest link that defines how your application appears when installed on devices.
+	*
+	* @param valueOrFn - The manifest URL or a callback function receiving helper utilities
+	* @returns The builder instance for method chaining
+	*
+	* @example
+	* new HeadBuilder({ metadataBase: new URL('https://devsantara.com') })
+	*   .addManifest((helper) => helper.resolveUrl('/manifest.json'))
+	*   .build();
+	*/
+	addManifest(valueOrFn) {
+		const href = this.parseValueOrFn(valueOrFn);
+		return this.addElement("link", {
+			rel: "manifest",
+			href: href.toString()
+		});
+	}
+	/**
+	* Adds an external CSS stylesheet link to the page.
+	*
+	* @param href - The stylesheet URL
+	* @param options - Additional link attributes (media queries, integrity, etc.)
+	* @returns The builder instance for method chaining
+	*
+	* @example
+	* new HeadBuilder()
+	*   .addStylesheet('/styles.css', { media: 'print' })
+	*   .build();
+	*/
+	addStylesheet(href, options) {
+		return this.addElement("link", {
+			rel: "stylesheet",
+			href: href.toString(),
+			...options
+		});
+	}
+	/**
+	* Adds a favicon or app icon using preset types or custom rel values.
+	*
+	* @param preset - Icon type ('icon', 'apple', 'shortcut', or custom string)
+	* @param valueOrFn - Icon configuration or a callback function receiving helper utilities
+	* @returns The builder instance for method chaining
+	*
+	* @example
+	* new HeadBuilder({ metadataBase: new URL('https://devsantara.com') })
+	*   .addIcon('apple', (helper) => ({
+	*     href: helper.resolveUrl('/apple-icon.png'),
+	*     sizes: '180x180'
+	*   }))
+	*   .build();
+	*/
+	addIcon(preset, valueOrFn) {
+		const options = this.parseValueOrFn(valueOrFn);
+		const rel = {
+			apple: "apple-touch-icon",
+			icon: "icon",
+			shortcut: "shortcut icon"
+		}[preset] || preset;
+		return this.addElement("link", {
+			rel,
+			href: options.href.toString(),
+			type: options.type,
+			sizes: options.sizes,
+			media: options.media,
+			fetchPriority: options.fetchPriority
+		});
+	}
+	/**
+	* Builds and returns the final head configuration. Returns adapted output if an adapter was provided, otherwise returns `HeadElement[]`.
+	*
+	* @returns The head configuration in the target format
+	*/
+	build() {
+		if (this.adapter) return this.adapter.transform(this.elements);
+		return this.elements;
+	}
+};
+
+//#endregion
+export { HeadBuilder };