alepha/dist/react/head/index.d.ts

Easy-to-use modern TypeScript framework for building many kind of applications.

import { Alepha, KIND, Primitive } from "alepha";
//#region ../../src/react/head/interfaces/Head.d.ts
/**
 * Complete head configuration combining basic head elements with SEO fields.
 *
 * @example
 * ```ts
 * $head({
 *   title: "My App",
 *   description: "Build amazing apps",
 *   image: "https://example.com/og.png",
 *   url: "https://example.com/",
 *   siteName: "My App",
 *   twitter: { card: "summary_large_image" },
 * })
 * ```
 */
interface Head extends SimpleHead, Seo {}
/**
 * SEO configuration for automatic meta tag generation.
 * Fields are used for meta description, OpenGraph, and Twitter Card tags.
 */
interface Seo {
  /**
   * Page description - used for meta description, og:description, twitter:description
   */
  description?: string;
  /**
   * Primary image URL - used for og:image and twitter:image
   */
  image?: string;
  /**
   * Canonical URL - used for og:url and link rel="canonical"
   */
  url?: string;
  /**
   * Site name - used for og:site_name
   */
  siteName?: string;
  /**
   * Locale - used for og:locale (e.g., "en_US")
   */
  locale?: string;
  /**
   * Content type - used for og:type (default: "website")
   */
  type?: "website" | "article" | "product" | "profile" | string;
  /**
   * Image width in pixels - used for og:image:width
   */
  imageWidth?: number;
  /**
   * Image height in pixels - used for og:image:height
   */
  imageHeight?: number;
  /**
   * Image alt text - used for og:image:alt and twitter:image:alt
   */
  imageAlt?: string;
  /**
   * Twitter-specific overrides
   */
  twitter?: {
    /**
     * Twitter card type
     */
    card?: "summary" | "summary_large_image" | "app" | "player";
    /**
     * @username of website
     */
    site?: string;
    /**
     * @username of content creator
     */
    creator?: string;
    /**
     * Override title for Twitter
     */
    title?: string;
    /**
     * Override description for Twitter
     */
    description?: string;
    /**
     * Override image for Twitter
     */
    image?: string;
  };
  /**
   * OpenGraph-specific overrides
   */
  og?: {
    /**
     * Override title for OpenGraph
     */
    title?: string;
    /**
     * Override description for OpenGraph
     */
    description?: string;
    /**
     * Override image for OpenGraph
     */
    image?: string;
  };
}
interface SimpleHead {
  title?: string;
  titleSeparator?: string;
  /**
   * Document charset - defaults to "UTF-8" if not specified
   */
  charset?: string;
  /**
   * Viewport content - defaults to "width=device-width, initial-scale=1" if not specified
   */
  viewport?: string;
  htmlAttributes?: Record<string, string>;
  bodyAttributes?: Record<string, string>;
  /**
   * Meta tags - supports both name and property attributes
   */
  meta?: Array<HeadMeta>;
  /**
   * Link tags (e.g., stylesheets, preload, canonical)
   */
  link?: Array<{
    rel: string;
    href: string;
    type?: string;
    as?: string;
    crossorigin?: string;
    /**
     * Media query — used for theme-aware icons and responsive stylesheets.
     * e.g. `(prefers-color-scheme: dark)` to ship a dark-mode favicon.
     */
    media?: string;
    /**
     * Sizes attribute — used for icon link tags (e.g. `"32x32"`, `"any"`).
     */
    sizes?: string;
    /**
     * Hreflang attribute — used for `rel="alternate"` localized variants.
     */
    hreflang?: string;
  }>;
  /**
   * Script tags - string for inline code, or object with attributes
   */
  script?: Array<string | (Record<string, string | boolean | undefined> & {
    /**
     * Inline JavaScript code
     */
    content?: string;
  })>;
}
interface HeadMeta {
  /**
   * Meta name attribute (e.g., "description", "twitter:card")
   */
  name?: string;
  /**
   * Meta property attribute (e.g., "og:title", "og:image")
   */
  property?: string;
  /**
   * Meta content value
   */
  content: string;
}
//#endregion
//#region ../../src/react/head/helpers/SeoExpander.d.ts
/**
 * Expands Head configuration into SEO meta tags.
 *
 * Generates:
 * - `<meta name="description">` from head.description
 * - `<meta property="og:*">` OpenGraph tags
 * - `<meta name="twitter:*">` Twitter Card tags
 *
 * @example
 * ```ts
 * const helper = new SeoExpander();
 * const { meta, link } = helper.expand({
 *   title: "My App",
 *   description: "Build amazing apps",
 *   image: "https://example.com/og.png",
 *   url: "https://example.com/",
 * });
 * ```
 */
declare class SeoExpander {
  expand(head: Head): {
    meta: HeadMeta[];
    link: Array<{
      rel: string;
      href: string;
    }>;
  };
  protected expandOpenGraph(head: Head, meta: HeadMeta[]): void;
  protected expandTwitter(head: Head, meta: HeadMeta[]): void;
}
//#endregion
//#region ../../src/react/head/hooks/useHead.d.ts
/**
 * ```tsx
 * const App = () => {
 *   const [head, setHead] = useHead({
 *     // will set the document title on the first render
 *     title: "My App",
 *   });
 *
 *   return (
 *     // This will update the document title when the button is clicked
 *     <button onClick={() => setHead({ title: "Change Title" })}>
 *       Change Title {head.title}
 *     </button>
 *   );
 * }
 * ```
 */
declare const useHead: (options?: UseHeadOptions) => UseHeadReturn;
type UseHeadOptions = Head | ((previous?: Head) => Head);
type UseHeadReturn = [Head, (head?: Head | ((previous?: Head) => Head)) => void];
//#endregion
//#region ../../src/react/head/providers/HeadProvider.d.ts
/**
 * Provides methods to fill and merge head information into the application state.
 *
 * Used both on server and client side to manage document head.
 *
 * @see {@link SeoExpander}
 * @see {@link ServerHeadProvider}
 * @see {@link BrowserHeadProvider}
 */
declare class HeadProvider {
  protected readonly log: import("alepha/logger").Logger;
  protected readonly seoExpander: SeoExpander;
  global?: Array<Head | (() => Head)>;
  /**
   * Track if we've warned about page-level htmlAttributes to avoid spam.
   */
  protected warnedAboutHtmlAttributes: boolean;
  /**
   * Resolve global head configuration (from $head primitives only).
   *
   * This is used to get htmlAttributes early, before page loaders run.
   * Only htmlAttributes from global $head are allowed; page-level htmlAttributes
   * are ignored for early streaming optimization.
   *
   * @returns Merged global head with htmlAttributes
   */
  resolveGlobalHead(): Head;
  /**
   * Fully resolve all global $head entries (functions re-evaluated, objects kept as-is).
   *
   * Unlike resolveGlobalHead() which only extracts htmlAttributes for streaming,
   * this resolves all head properties (meta, link, script, htmlAttributes, etc.).
   *
   * Used by BrowserHeadProvider.refreshGlobalHead() to re-apply global head to the DOM.
   */
  resolveGlobal(): Head;
  fillHead(state: HeadState): void;
  protected mergeHead(state: HeadState, head: Head): void;
  protected fillHeadByPage(page: HeadRoute, state: HeadState, props: Record<string, any>): void;
}
/**
 * Minimal route interface for head processing.
 * Avoids circular dependency with alepha/react/router.
 */
interface HeadRoute {
  head?: Head | ((props: Record<string, any>, previous?: Head) => Head);
}
/**
 * Minimal state interface for head processing.
 * Avoids circular dependency with alepha/react/router.
 */
interface HeadState {
  head: Head;
  layers: Array<{
    route?: HeadRoute;
    props?: Record<string, any>;
    error?: Error;
  }>;
}
//#endregion
//#region ../../src/react/head/primitives/$head.d.ts
/**
 * Set global `<head>` options for the application.
 */
declare const $head: {
  (options: HeadPrimitiveOptions): HeadPrimitive;
  [KIND]: typeof HeadPrimitive;
};
type HeadPrimitiveOptions = Head | (() => Head);
declare class HeadPrimitive extends Primitive<HeadPrimitiveOptions> {
  protected readonly provider: HeadProvider;
  protected onInit(): void;
}
//#endregion
//#region ../../src/react/head/providers/BrowserHeadProvider.d.ts
/**
 * Browser-side head provider that manages document head elements.
 *
 * Used by ReactBrowserProvider and ReactBrowserRouterProvider to update
 * document title, meta tags, and other head elements during client-side
 * navigation.
 */
declare class BrowserHeadProvider {
  protected readonly alepha: Alepha;
  protected readonly headProvider: HeadProvider;
  protected get document(): Document;
  /**
   * Fill head state from route configurations and render to document.
   * Combines fillHead from HeadProvider with renderHead to the DOM.
   *
   * Only runs in browser environment - no-op on server.
   */
  fillAndRenderHead(state: {
    head: Head;
    layers: Array<any>;
  }): void;
  /**
   * Re-evaluate all global $head entries and apply the result to the DOM.
   *
   * Call this when something that affects global $head output changes at runtime
   * (e.g., theme switch). Page-level head (title, meta from routes) is not touched.
   */
  refreshGlobalHead(): void;
  getHead(document: Document): Head;
  renderHead(document: Document, head: Head): void;
  protected renderScriptTag(document: Document, script: string | (Record<string, string | boolean | undefined> & {
    content?: string;
  })): void;
  /**
   * Find an existing inline `<script>` tag (no `src`) with matching textContent.
   * Used to make `renderScriptTag` idempotent across hydration + navigation,
   * so SSR-emitted global scripts aren't re-appended client-side.
   */
  protected findInlineScriptByContent(document: Document, content: string): Element | null;
  protected renderMetaTag(document: Document, meta: HeadMeta): void;
}
//#endregion
//#region ../../src/react/head/providers/ServerHeadProvider.d.ts
/**
 * Server-side head provider that fills head content from route configurations.
 *
 * Used by ReactServerProvider to collect title, meta tags, and other head
 * elements which are then rendered by ReactServerTemplateProvider.
 */
declare class ServerHeadProvider {
  protected readonly headProvider: HeadProvider;
  /**
   * Resolve global head configuration (htmlAttributes only).
   *
   * Used for early streaming optimization - htmlAttributes can be sent
   * before page loaders run since they come from global $head only.
   */
  resolveGlobalHead(): Head;
  /**
   * Fill head state from route configurations.
   * Delegates to HeadProvider to merge head data from all route layers.
   */
  fillHead(state: {
    head: SimpleHead;
    layers: Array<any>;
  }): void;
}
//#endregion
//#region ../../src/react/head/index.d.ts
/**
 * HTML head element management.
 *
 * **Features:**
 * - Title, meta tags, and links
 * - SEO optimization
 * - Social media tags
 *
 * @module alepha.react.head
 */
declare const AlephaReactHead: import("alepha").Service<import("alepha").Module>;
//#endregion
export { $head, AlephaReactHead, BrowserHeadProvider, Head, HeadMeta, HeadPrimitive, HeadPrimitiveOptions, Seo, SeoExpander, ServerHeadProvider, SimpleHead, UseHeadOptions, UseHeadReturn, useHead };
//# sourceMappingURL=index.d.ts.map