alepha 0.15.0 → 0.15.2

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

@@ -0,0 +1,288 @@
+import * as alepha0 from "alepha";
+import { Alepha, KIND, Primitive } from "alepha";
+import * as alepha_logger0 from "alepha/logger";
+
+//#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;
+  }>;
+  /** 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: alepha_logger0.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;
+  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;
+  getHead(document: Document): Head;
+  renderHead(document: Document, head: Head): void;
+  protected renderScriptTag(document: Document, script: string | (Record<string, string | boolean | undefined> & {
+    content?: string;
+  })): void;
+  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
+/**
+ * | type | quality | stability |
+ * |------|---------|-----------|
+ * | frontend | standard | stable |
+ *
+ * HTML head element management.
+ *
+ * **Features:**
+ * - Title, meta tags, and links
+ * - SEO optimization
+ * - Social media tags
+ *
+ * @module alepha.react.head
+ */
+declare const AlephaReactHead: alepha0.Service<alepha0.Module>;
+//#endregion
+export { $head, AlephaReactHead, BrowserHeadProvider, Head, HeadMeta, HeadPrimitive, HeadPrimitiveOptions, Seo, SeoExpander, ServerHeadProvider, SimpleHead, UseHeadOptions, UseHeadReturn, useHead };
+//# sourceMappingURL=index.d.ts.map

package/dist/react/head/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../../src/react/head/interfaces/Head.ts","../../../src/react/head/helpers/SeoExpander.ts","../../../src/react/head/hooks/useHead.ts","../../../src/react/head/providers/HeadProvider.ts","../../../src/react/head/primitives/$head.ts","../../../src/react/head/providers/BrowserHeadProvider.ts","../../../src/react/head/providers/ServerHeadProvider.ts","../../../src/react/head/index.ts"],"mappings":"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"}