@alepha/react 0.14.2 → 0.14.4

package/dist/head/index.d.ts

@@ -1,543 +1,9 @@
-import { ClientOnlyProps } from "@alepha/react";
-import * as alepha15 from "alepha";
-import { Alepha, AlephaError, Async, KIND, Primitive, Static, TSchema } from "alepha";
-import { ServerRequest, ServerTimingProvider } from "alepha/server";
-import { FC, ReactNode } from "react";
-import { ServerRouteCache } from "alepha/server/cache";
-import "alepha/logger";
-import "alepha/datetime";
-import "alepha/server/links";
-import "alepha/router";
-import "react/jsx-runtime";
-import "alepha/server/static";
+import * as alepha0 from "alepha";
+import { Alepha, KIND, Primitive } from "alepha";
+import * as alepha_logger0 from "alepha/logger";
 
-//#region ../../src/router/errors/Redirection.d.ts
-
-/**
- * Used for Redirection during the page loading.
- *
- * Depends on the context, it can be thrown or just returned.
- *
- * @example
- * ```ts
- * import { Redirection } from "@alepha/react";
- *
- * const MyPage = $page({
- *   resolve: async () => {
- *    if (needRedirect) {
- *      throw new Redirection("/new-path");
- *    }
- *   },
- * });
- * ```
- */
-declare class Redirection extends AlephaError {
-  readonly redirect: string;
-  constructor(redirect: string);
-}
-//#endregion
-//#region ../../src/router/providers/ReactPageProvider.d.ts
-declare const envSchema$2: alepha15.TObject<{
-  REACT_STRICT_MODE: alepha15.TBoolean;
-}>;
-declare module "alepha" {
-  interface Env extends Partial<Static<typeof envSchema$2>> {}
-}
-/**
- * Handle page routes for React applications. (Browser and Server)
- */
-
-interface PageRouteEntry extends Omit<PagePrimitiveOptions, "children" | "parent"> {
-  children?: PageRouteEntry[];
-}
-interface PageRoute extends PageRouteEntry {
-  type: "page";
-  name: string;
-  parent?: PageRoute;
-  match: string;
-}
-interface Layer {
-  config?: {
-    query?: Record<string, any>;
-    params?: Record<string, any>;
-    context?: Record<string, any>;
-  };
-  name: string;
-  props?: Record<string, any>;
-  error?: Error;
-  part?: string;
-  element: ReactNode;
-  index: number;
-  path: string;
-  route?: PageRoute;
-  cache?: boolean;
-}
-type PreviousLayerData = Omit<Layer, "element" | "index" | "path">;
-interface ReactRouterState {
-  /**
-   * Stack of layers for the current page.
-   */
-  layers: Array<Layer>;
-  /**
-   * URL of the current page.
-   */
-  url: URL;
-  /**
-   * Error handler for the current page.
-   */
-  onError: ErrorHandler;
-  /**
-   * Params extracted from the URL for the current page.
-   */
-  params: Record<string, any>;
-  /**
-   * Query parameters extracted from the URL for the current page.
-   */
-  query: Record<string, string>;
-  /**
-   * Optional meta information associated with the current page.
-   */
-  meta: Record<string, any>;
-  name?: string;
-}
-//#endregion
-//#region ../../src/router/services/ReactPageService.d.ts
-/**
- * $page methods interface.
- */
-declare abstract class ReactPageService {
-  fetch(pathname: string, options?: PagePrimitiveRenderOptions): Promise<{
-    html: string;
-    response: Response;
-  }>;
-  render(name: string, options?: PagePrimitiveRenderOptions): Promise<PagePrimitiveRenderResult>;
-}
-//#endregion
-//#region ../../src/router/primitives/$page.d.ts
-
-interface PagePrimitiveOptions<TConfig extends PageConfigSchema = PageConfigSchema, TProps extends object = TPropsDefault, TPropsParent extends object = TPropsParentDefault> {
-  /**
-   * Identifier name for the page. Must be unique.
-   *
-   * @default Primitive key
-   */
-  name?: string;
-  /**
-   * Add a pathname to the page.
-   *
-   * Pathname can contain parameters, like `/post/:slug`.
-   *
-   * @default ""
-   */
-  path?: string;
-  /**
-   * Add an input schema to define:
-   * - `params`: parameters from the pathname.
-   * - `query`: query parameters from the URL.
-   */
-  schema?: TConfig;
-  /**
-   * Load data before rendering the page.
-   *
-   * This function receives
-   * - the request context (params, query, etc.)
-   * - the parent props (if page has a parent)
-   *
-   * > In SSR, the returned data will be serialized and sent to the client, then reused during the client-side hydration.
-   *
-   * Resolve can be stopped by throwing an error, which will be handled by the `errorHandler` function.
-   * It's common to throw a `NotFoundError` to display a 404 page.
-   *
-   * RedirectError can be thrown to redirect the user to another page.
-   */
-  resolve?: (context: PageResolve<TConfig, TPropsParent>) => Async<TProps>;
-  /**
-   * Default props to pass to the component when rendering the page.
-   *
-   * Resolved props from the `resolve` function will override these default props.
-   */
-  props?: () => Partial<TProps>;
-  /**
-   * The component to render when the page is loaded.
-   *
-   * If `lazy` is defined, this will be ignored.
-   * Prefer using `lazy` to improve the initial loading time.
-   */
-  component?: FC<TProps & TPropsParent>;
-  /**
-   * Lazy load the component when the page is loaded.
-   *
-   * It's recommended to use this for components to improve the initial loading time
-   * and enable code-splitting.
-   */
-  lazy?: () => Promise<{
-    default: FC<TProps & TPropsParent>;
-  }>;
-  /**
-   * Attach child pages to create nested routes.
-   * This will make the page a parent route.
-   */
-  children?: Array<PagePrimitive> | (() => Array<PagePrimitive>);
-  /**
-   * Define a parent page for nested routing.
-   */
-  parent?: PagePrimitive<PageConfigSchema, TPropsParent, any>;
-  /**
-   * Function to determine if the page can be accessed.
-   *
-   * If it returns false, the page will not be accessible and a 403 Forbidden error will be returned.
-   * This function can be used to implement permission-based access control.
-   */
-  can?: () => boolean;
-  /**
-   * Catch any error from the `resolve` function or during `rendering`.
-   *
-   * Expected to return one of the following:
-   * - a ReactNode to render an error page
-   * - a Redirection to redirect the user
-   * - undefined to let the error propagate
-   *
-   * If not defined, the error will be thrown and handled by the server or client error handler.
-   * If a leaf $page does not define an error handler, the error can be caught by parent pages.
-   *
-   * @example Catch a 404 from API and render a custom not found component:
-   * ```ts
-   * resolve: async ({ params, query }) => {
-   *    api.fetch("/api/resource", { params, query });
-   * },
-   * errorHandler: (error, context) => {
-   *   if (HttpError.is(error, 404)) {
-   *     return <ResourceNotFound />;
-   *   }
-   * }
-   * ```
-   *
-   * @example Catch an 401 error and redirect the user to the login page:
-   * ```ts
-   * resolve: async ({ params, query }) => {
-   *   // but the user is not authenticated
-   *   api.fetch("/api/resource", { params, query });
-   * },
-   * errorHandler: (error, context) => {
-   *   if (HttpError.is(error, 401)) {
-   *     // throwing a Redirection is also valid!
-   *     return new Redirection("/login");
-   *   }
-   * }
-   * ```
-   */
-  errorHandler?: ErrorHandler;
-  /**
-   * If true, the page will be considered as a static page, immutable and cacheable.
-   * Replace boolean by an object to define static entries. (e.g. list of params/query)
-   *
-   * Browser-side: it only works with `alepha/vite`, which can pre-render the page at build time.
-   *
-   * Server-side: It will act as timeless cached page. You can use `cache` to configure the cache behavior.
-   */
-  static?: boolean | {
-    entries?: Array<Partial<PageRequestConfig<TConfig>>>;
-  };
-  cache?: ServerRouteCache;
-  /**
-   * If true, force the page to be rendered only on the client-side (browser).
-   * It uses the `<ClientOnly/>` component to render the page.
-   */
-  client?: boolean | ClientOnlyProps;
-  /**
-   * Called before the server response is sent to the client. (server only)
-   */
-  onServerResponse?: (request: ServerRequest) => unknown;
-  /**
-   * Called when user leaves the page. (browser only)
-   */
-  onLeave?: () => void;
-  /**
-   * @experimental
-   *
-   * Add a css animation when the page is loaded or unloaded.
-   * It uses CSS animations, so you need to define the keyframes in your CSS.
-   *
-   * @example Simple animation name
-   * ```ts
-   * animation: "fadeIn"
-   * ```
-   *
-   * CSS example:
-   * ```css
-   * @keyframes fadeIn {
-   *  from { opacity: 0; }
-   *  to { opacity: 1; }
-   * }
-   * ```
-   *
-   * @example Detailed animation
-   * ```ts
-   * animation: {
-   *   enter: { name: "fadeIn", duration: 300 },
-   *   exit: { name: "fadeOut", duration: 200, timing: "ease-in-out" },
-   * }
-   * ```
-   *
-   * @example Only exit animation
-   * ```ts
-   * animation: {
-   *   exit: "fadeOut"
-   * }
-   * ```
-   *
-   * @example With custom timing function
-   * ```ts
-   * animation: {
-   *   enter: { name: "fadeIn", duration: 300, timing: "cubic-bezier(0.4, 0, 0.2, 1)" },
-   *   exit: { name: "fadeOut", duration: 200, timing: "ease-in-out" },
-   * }
-   * ```
-   */
-  animation?: PageAnimation;
-}
-type ErrorHandler = (error: Error, state: ReactRouterState) => ReactNode | Redirection | undefined;
-declare class PagePrimitive<TConfig extends PageConfigSchema = PageConfigSchema, TProps extends object = TPropsDefault, TPropsParent extends object = TPropsParentDefault> extends Primitive<PagePrimitiveOptions<TConfig, TProps, TPropsParent>> {
-  protected readonly reactPageService: ReactPageService;
-  protected onInit(): void;
-  get name(): string;
-  /**
-   * For testing or build purposes.
-   *
-   * This will render the page (HTML layout included or not) and return the HTML + context.
-   * Only valid for server-side rendering, it will throw an error if called on the client-side.
-   */
-  render(options?: PagePrimitiveRenderOptions): Promise<PagePrimitiveRenderResult>;
-  fetch(options?: PagePrimitiveRenderOptions): Promise<{
-    html: string;
-    response: Response;
-  }>;
-  match(url: string): boolean;
-  pathname(config: any): string;
-}
-interface PageConfigSchema {
-  query?: TSchema;
-  params?: TSchema;
-}
-type TPropsDefault = any;
-type TPropsParentDefault = {};
-interface PagePrimitiveRenderOptions {
-  params?: Record<string, string>;
-  query?: Record<string, string>;
-  /**
-   * If true, the HTML layout will be included in the response.
-   * If false, only the page content will be returned.
-   *
-   * @default true
-   */
-  html?: boolean;
-  hydration?: boolean;
-}
-interface PagePrimitiveRenderResult {
-  html: string;
-  state: ReactRouterState;
-  redirect?: string;
-}
-interface PageRequestConfig<TConfig extends PageConfigSchema = PageConfigSchema> {
-  params: TConfig["params"] extends TSchema ? Static<TConfig["params"]> : Record<string, string>;
-  query: TConfig["query"] extends TSchema ? Static<TConfig["query"]> : Record<string, string>;
-}
-type PageResolve<TConfig extends PageConfigSchema = PageConfigSchema, TPropsParent extends object = TPropsParentDefault> = PageRequestConfig<TConfig> & TPropsParent & Omit<ReactRouterState, "layers" | "onError">;
-type PageAnimation = PageAnimationObject | ((state: ReactRouterState) => PageAnimationObject | undefined);
-type PageAnimationObject = CssAnimationName | {
-  enter?: CssAnimation | CssAnimationName;
-  exit?: CssAnimation | CssAnimationName;
-};
-type CssAnimationName = string;
-type CssAnimation = {
-  name: string;
-  duration?: number;
-  timing?: string;
-};
-//#endregion
-//#region ../../src/core/index.d.ts
-declare module "alepha" {
-  interface Hooks {
-    /**
-     * Fires when a user action is starting.
-     * Action can be a form submission, a route transition, or a custom action.
-     */
-    "react:action:begin": {
-      type: string;
-      id?: string;
-    };
-    /**
-     * Fires when a user action has succeeded.
-     * Action can be a form submission, a route transition, or a custom action.
-     */
-    "react:action:success": {
-      type: string;
-      id?: string;
-    };
-    /**
-     * Fires when a user action has failed.
-     * Action can be a form submission, a route transition, or a custom action.
-     */
-    "react:action:error": {
-      type: string;
-      id?: string;
-      error: Error;
-    };
-    /**
-     * Fires when a user action has completed, regardless of success or failure.
-     * Action can be a form submission, a route transition, or a custom action.
-     */
-    "react:action:end": {
-      type: string;
-      id?: string;
-    };
-  }
-}
-/**
- * Provides full-stack React development with declarative routing, server-side rendering, and client-side hydration.
- *
- * The React module enables building modern React applications using the `$page` primitive on class properties.
- * It delivers seamless server-side rendering, automatic code splitting, and client-side navigation with full
- * type safety and schema validation for route parameters and data.
- *
- * @see {@link $page}
- * @module alepha.react
- */
-//#endregion
-//#region ../../src/router/providers/ReactBrowserProvider.d.ts
-declare const envSchema$1: alepha15.TObject<{
-  REACT_ROOT_ID: alepha15.TString;
-}>;
-declare module "alepha" {
-  interface Env extends Partial<Static<typeof envSchema$1>> {}
-}
-/**
- * React browser renderer configuration atom
- */
-declare const reactBrowserOptions: alepha15.Atom<alepha15.TObject<{
-  scrollRestoration: alepha15.TUnsafe<"top" | "manual">;
-}>, "alepha.react.browser.options">;
-type ReactBrowserRendererOptions = Static<typeof reactBrowserOptions.schema>;
-declare module "alepha" {
-  interface State {
-    [reactBrowserOptions.key]: ReactBrowserRendererOptions;
-  }
-}
-type ReactHydrationState = {
-  layers?: Array<PreviousLayerData>;
-} & {
-  [key: string]: any;
-};
-//#endregion
-//#region ../../src/router/providers/ReactServerProvider.d.ts
-declare const envSchema: alepha15.TObject<{
-  REACT_SSR_ENABLED: alepha15.TOptional<alepha15.TBoolean>;
-  REACT_ROOT_ID: alepha15.TString;
-}>;
-declare module "alepha" {
-  interface Env extends Partial<Static<typeof envSchema>> {}
-  interface State {
-    "alepha.react.server.ssr"?: boolean;
-    "alepha.react.server.template"?: string;
-  }
-}
-/**
- * React server provider configuration atom
- */
-declare const reactServerOptions: alepha15.Atom<alepha15.TObject<{
-  publicDir: alepha15.TString;
-  staticServer: alepha15.TObject<{
-    disabled: alepha15.TBoolean;
-    path: alepha15.TString;
-  }>;
-}>, "alepha.react.server.options">;
-type ReactServerProviderOptions = Static<typeof reactServerOptions.schema>;
-declare module "alepha" {
-  interface State {
-    [reactServerOptions.key]: ReactServerProviderOptions;
-  }
-}
-/**
- * React server provider responsible for SSR and static file serving.
- *
- * Use `react-dom/server` under the hood.
- */
-//#endregion
-//#region ../../src/router/index.d.ts
-declare module "alepha" {
-  interface State {
-    "alepha.react.router.state"?: ReactRouterState;
-  }
-  interface Hooks {
-    /**
-     * Fires when the React application is starting to be rendered on the server.
-     */
-    "react:server:render:begin": {
-      request?: ServerRequest;
-      state: ReactRouterState;
-    };
-    /**
-     * Fires when the React application has been rendered on the server.
-     */
-    "react:server:render:end": {
-      request?: ServerRequest;
-      state: ReactRouterState;
-      html: string;
-    };
-    /**
-     * Fires when the React application is being rendered on the browser.
-     */
-    "react:browser:render": {
-      root: HTMLElement;
-      element: ReactNode;
-      state: ReactRouterState;
-      hydration?: ReactHydrationState;
-    };
-    /**
-     * Fires when a route transition is starting.
-     */
-    "react:transition:begin": {
-      previous: ReactRouterState;
-      state: ReactRouterState;
-      animation?: PageAnimation;
-    };
-    /**
-     * Fires when a route transition has succeeded.
-     */
-    "react:transition:success": {
-      state: ReactRouterState;
-    };
-    /**
-     * Fires when a route transition has failed.
-     */
-    "react:transition:error": {
-      state: ReactRouterState;
-      error: Error;
-    };
-    /**
-     * Fires when a route transition has completed, regardless of success or failure.
-     */
-    "react:transition:end": {
-      state: ReactRouterState;
-    };
-  }
-}
-/**
- * Provides declarative routing with the `$page` primitive for building type-safe React routes.
- *
- * This module enables:
- * - URL pattern matching with parameters (e.g., `/users/:id`)
- * - Nested routing with parent-child relationships
- * - Type-safe URL parameter and query string validation
- * - Server-side data fetching with the `resolve` function
- * - Lazy loading and code splitting
- * - Page animations and error handling
- *
- * @see {@link $page}
- * @module alepha.react.router
- */
-//#endregion
 //#region ../../src/head/interfaces/Head.d.ts
+
 /**
  * Complete head configuration combining basic head elements with SEO fields.
  *
@@ -659,12 +125,55 @@ declare class SeoExpander {
 }
 //#endregion
 //#region ../../src/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)>;
-  fillHead(state: ReactRouterState): void;
-  protected mergeHead(state: ReactRouterState, head: Head): void;
-  protected fillHeadByPage(page: PageRoute, state: ReactRouterState, props: Record<string, any>): void;
+  /**
+   * 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/head/primitives/$head.d.ts
@@ -704,29 +213,59 @@ type UseHeadOptions = Head | ((previous?: Head) => Head);
 type UseHeadReturn = [Head, (head?: Head | ((previous?: Head) => Head)) => void];
 //#endregion
 //#region ../../src/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;
-  protected readonly serverTimingProvider: ServerTimingProvider;
-  protected readonly onServerRenderEnd: alepha15.HookPrimitive<"react:server:render:end">;
-  renderHead(template: string, head: SimpleHead): string;
-  protected mergeAttributes(existing: string, attrs: Record<string, string>): string;
-  protected parseAttributes(attrStr: string): Record<string, string>;
-  protected escapeHtml(str: string): string;
-  protected renderMetaTag(meta: HeadMeta): string;
-  protected renderScriptTag(script: Record<string, string | boolean>): string;
+  /**
+   * 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/head/index.d.ts
-declare module "@alepha/react/router" {
-  interface PagePrimitiveOptions<TConfig extends PageConfigSchema = PageConfigSchema, TProps extends object = TPropsDefault, TPropsParent extends object = TPropsParentDefault> {
-    head?: Head | ((props: TProps, previous?: Head) => Head);
-  }
-}
-declare module "@alepha/react/router" {
-  interface ReactRouterState {
+//#region ../../src/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 renderMetaTag(document: Document, meta: HeadMeta): void;
 }
+//#endregion
+//#region ../../src/head/index.d.ts
 /**
  * Fill `<head>` server & client side.
  *
@@ -738,7 +277,7 @@ declare module "@alepha/react/router" {
  * @see {@link ServerHeadProvider}
  * @module alepha.react.head
  */
-declare const AlephaReactHead: alepha15.Service<alepha15.Module>;
+declare const AlephaReactHead: alepha0.Service<alepha0.Module>;
 //#endregion
-export { $head, AlephaReactHead, Head, HeadMeta, HeadPrimitive, HeadPrimitiveOptions, Seo, SeoExpander, ServerHeadProvider, SimpleHead, UseHeadOptions, UseHeadReturn, useHead };
+export { $head, AlephaReactHead, BrowserHeadProvider, Head, HeadMeta, HeadPrimitive, HeadPrimitiveOptions, Seo, SeoExpander, ServerHeadProvider, SimpleHead, UseHeadOptions, UseHeadReturn, useHead };
 //# sourceMappingURL=index.d.ts.map