@devsantara/head 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,293 @@
+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";
+
+//#region src/builder.d.ts
+/**
+ * Helper object provided to callback functions with utilities for dynamic metadata generation.
+ */
+interface BuilderHelper {
+  /**
+   * 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: string | URL) => string;
+}
+/**
+ * Generic type for builder method options that can accept either a value or a function
+ */
+type BuilderOption<T> = T | ((helper: BuilderHelper) => T);
+declare class HeadBuilder<TOutput = HeadElement[]> {
+  private metadataBase?;
+  private elements;
+  private 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
+   */
+  private parseValueOrFn;
+  /**
+   * 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?: {
+    metadataBase?: URL;
+    adapter?: HeadAdapter<TOutput>;
+  });
+  /**
+   * 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
+   */
+  private resolveUrl;
+  /**
+   * 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
+   */
+  private addElement;
+  /**
+   * 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: HeadAttributeTypeMap['meta']): this;
+  /**
+   * 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: HeadAttributeTypeMap['link']): this;
+  /**
+   * 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: HeadAttributeTypeMap['script']): this;
+  /**
+   * 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: HeadAttributeTypeMap['style']): this;
+  /**
+   * 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: CharSet): this;
+  /**
+   * 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: ColorScheme): this;
+  /**
+   * 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: string): this;
+  /**
+   * 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: ViewportOptions): this;
+  /**
+   * 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: string): this;
+  /**
+   * 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: BuilderOption<string | URL>): this;
+  /**
+   * 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: RobotsOptions): this;
+  /**
+   * 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: BuilderOption<OpenGraphOptions>): 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: BuilderOption<TwitterOptions>): 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<TLocale extends string = string>(valueOrFn: BuilderOption<AlternateLocaleOptions<TLocale>>): 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: BuilderOption<string | URL>): this;
+  /**
+   * 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: string | URL, options?: StylesheetOptions): this;
+  /**
+   * 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: IconPreset, valueOrFn: BuilderOption<IconOptions>): this;
+  /**
+   * 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(): TOutput;
+}
+//#endregion
+export { AlternateLocaleOptions, CharSet, ColorScheme, HeadAdapter, HeadAttributeTypeMap, HeadBuilder, HeadElement, HeadLinkAttributes, HeadMetaAttributes, HeadScriptAttributes, HeadStyleAttributes, HeadTitleAttributes, IconOptions, IconPreset, OpenGraphOptions, RobotsOptions, StylesheetOptions, TwitterOptions, ViewportOptions };