alepha 0.15.0 → 0.15.2

package/src/react/router/providers/ReactBrowserProvider.ts

@@ -0,0 +1,309 @@
+import {
+  $atom,
+  $hook,
+  $inject,
+  $use,
+  Alepha,
+  type State,
+  type Static,
+  t,
+} from "alepha";
+import { DateTimeProvider } from "alepha/datetime";
+import { $logger } from "alepha/logger";
+import { BrowserHeadProvider } from "alepha/react/head";
+import { LinkProvider } from "alepha/server/links";
+import type { RouterGoOptions } from "../services/ReactRouter.ts";
+import { ReactBrowserRouterProvider } from "./ReactBrowserRouterProvider.ts";
+import type {
+  PreviousLayerData,
+  ReactRouterState,
+} from "./ReactPageProvider.ts";
+
+export type { RouterGoOptions } from "../services/ReactRouter.ts";
+
+/**
+ * React browser renderer configuration atom
+ */
+export const reactBrowserOptions = $atom({
+  name: "alepha.react.browser.options",
+  schema: t.object({
+    scrollRestoration: t.enum(["top", "manual"]), // TODO: must be per page?
+  }),
+  default: {
+    scrollRestoration: "top" as const,
+  },
+});
+
+export type ReactBrowserRendererOptions = Static<
+  typeof reactBrowserOptions.schema
+>;
+
+declare module "alepha" {
+  interface State {
+    [reactBrowserOptions.key]: ReactBrowserRendererOptions;
+  }
+}
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+export class ReactBrowserProvider {
+  protected readonly log = $logger();
+  protected readonly client = $inject(LinkProvider);
+  protected readonly alepha = $inject(Alepha);
+  protected readonly router = $inject(ReactBrowserRouterProvider);
+  protected readonly dateTimeProvider = $inject(DateTimeProvider);
+  protected readonly browserHeadProvider = $inject(BrowserHeadProvider);
+
+  protected readonly options = $use(reactBrowserOptions);
+
+  public get rootId() {
+    return "root";
+  }
+
+  protected getRootElement() {
+    const root = this.document.getElementById(this.rootId);
+    if (root) {
+      return root;
+    }
+
+    const div = this.document.createElement("div");
+    div.id = this.rootId;
+
+    this.document.body.prepend(div);
+
+    return div;
+  }
+
+  public transitioning?: {
+    to: string;
+    from?: string;
+  };
+
+  public get state(): ReactRouterState {
+    return this.alepha.store.get("alepha.react.router.state")!;
+  }
+
+  /**
+   * Accessor for Document DOM API.
+   */
+  public get document() {
+    return window.document;
+  }
+
+  /**
+   * Accessor for History DOM API.
+   */
+  public get history() {
+    return window.history;
+  }
+
+  /**
+   * Accessor for Location DOM API.
+   */
+  public get location() {
+    return window.location;
+  }
+
+  public get base() {
+    const base = import.meta.env?.BASE_URL;
+    if (!base || base === "/") {
+      return "";
+    }
+
+    return base;
+  }
+
+  public get url(): string {
+    const url = this.location.pathname + this.location.search;
+    if (this.base) {
+      return url.replace(this.base, "");
+    }
+    return url;
+  }
+
+  public pushState(path: string, replace?: boolean) {
+    const url = this.base + path;
+
+    if (replace) {
+      this.history.replaceState({}, "", url);
+    } else {
+      this.history.pushState({}, "", url);
+    }
+  }
+
+  public async invalidate(props?: Record<string, any>) {
+    const previous: PreviousLayerData[] = [];
+
+    this.log.trace("Invalidating layers");
+
+    if (props) {
+      const [key] = Object.keys(props);
+      const value = props[key];
+
+      for (const layer of this.state.layers) {
+        if (layer.props?.[key]) {
+          previous.push({
+            ...layer,
+            props: {
+              ...layer.props,
+              [key]: value,
+            },
+          });
+          break;
+        }
+        previous.push(layer);
+      }
+    }
+
+    await this.render({ previous });
+  }
+
+  public async go(url: string, options: RouterGoOptions = {}): Promise<void> {
+    this.log.trace(`Going to ${url}`, {
+      url,
+      options,
+    });
+
+    await this.render({
+      url,
+      previous: options.force ? [] : this.state.layers,
+      meta: options.meta,
+    });
+
+    // when redirecting in browser
+    if (this.state.url.pathname + this.state.url.search !== url) {
+      this.pushState(this.state.url.pathname + this.state.url.search);
+      return;
+    }
+
+    this.pushState(url, options.replace);
+  }
+
+  protected async render(options: RouterRenderOptions = {}): Promise<void> {
+    const previous = options.previous ?? this.state.layers;
+    const url = options.url ?? this.url;
+    const start = this.dateTimeProvider.now();
+
+    this.transitioning = {
+      to: url,
+      from: this.state?.url.pathname,
+    };
+
+    this.log.debug("Transitioning...", {
+      to: url,
+    });
+
+    const redirect = await this.router.transition(
+      new URL(`http://localhost${url}`),
+      previous,
+      options.meta,
+    );
+
+    if (redirect) {
+      this.log.info("Redirecting to", {
+        redirect,
+      });
+
+      // if redirect is an absolute URL, use window.location.href (full page reload)
+      if (redirect.startsWith("http")) {
+        window.location.href = redirect;
+      } else {
+        // if redirect is a relative URL, use render() (single page app)
+        return await this.render({ url: redirect });
+      }
+    }
+
+    const ms = this.dateTimeProvider.now().diff(start);
+    this.log.info(`Transition OK [${ms}ms]`, this.transitioning);
+
+    this.transitioning = undefined;
+  }
+
+  /**
+   * Get embedded layers from the server.
+   */
+  protected getHydrationState(): ReactHydrationState | undefined {
+    try {
+      if ("__ssr" in window && typeof window.__ssr === "object") {
+        return window.__ssr as ReactHydrationState;
+      }
+    } catch (error) {
+      console.error(error);
+    }
+  }
+
+  // -------------------------------------------------------------------------------------------------------------------
+
+  protected readonly onTransitionEnd = $hook({
+    on: "react:transition:end",
+    handler: () => {
+      if (
+        this.options.scrollRestoration === "top" &&
+        typeof window !== "undefined" &&
+        !this.alepha.isTest()
+      ) {
+        this.log.trace("Restoring scroll position to top");
+        window.scrollTo(0, 0);
+      }
+    },
+  });
+
+  public readonly ready = $hook({
+    on: "ready",
+    handler: async () => {
+      const hydration = this.getHydrationState();
+      const previous = hydration?.layers ?? [];
+
+      if (hydration) {
+        // low budget, but works for now
+        for (const [key, value] of Object.entries(hydration)) {
+          if (key !== "layers") {
+            this.alepha.set(key as keyof State, value);
+          }
+        }
+      }
+
+      await this.render({ previous });
+
+      const element = this.router.root(this.state);
+
+      await this.alepha.events.emit("react:browser:render", {
+        element,
+        root: this.getRootElement(),
+        hydration,
+        state: this.state,
+      });
+
+      // Fill and render head from route configurations
+      this.browserHeadProvider.fillAndRenderHead(this.state);
+
+      window.addEventListener("popstate", () => {
+        // when you update silently queryParams or hash, skip rendering
+        // if you want to force a rendering, use #go()
+        if (this.base + this.state.url.pathname === this.location.pathname) {
+          return;
+        }
+
+        this.log.debug("Popstate event triggered - rendering new state", {
+          url: this.location.pathname + this.location.search,
+        });
+
+        this.render();
+      });
+    },
+  });
+}
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+export type ReactHydrationState = {
+  layers?: Array<PreviousLayerData>;
+} & {
+  [key: string]: any;
+};
+
+export interface RouterRenderOptions {
+  url?: string;
+  previous?: PreviousLayerData[];
+  meta?: Record<string, any>;
+}

package/src/react/router/providers/ReactBrowserRendererProvider.ts

@@ -0,0 +1,25 @@
+import { $hook } from "alepha";
+import { $logger } from "alepha/logger";
+import { createRoot, hydrateRoot, type Root } from "react-dom/client";
+
+/**
+ * Browser specific React renderer (react-dom/client interface)
+ */
+export class ReactBrowserRendererProvider {
+  protected readonly log = $logger();
+  protected root?: Root;
+
+  protected readonly onBrowserRender = $hook({
+    on: "react:browser:render",
+    handler: async ({ hydration, root, element }) => {
+      if (hydration?.layers) {
+        this.root = hydrateRoot(root, element);
+        this.log.info("Hydrated root element");
+      } else {
+        this.root ??= createRoot(root);
+        this.root.render(element);
+        this.log.info("Created root element");
+      }
+    },
+  });
+}

package/src/react/router/providers/ReactBrowserRouterProvider.ts

@@ -0,0 +1,168 @@
+import { $hook, $inject, Alepha } from "alepha";
+import { $logger } from "alepha/logger";
+import { BrowserHeadProvider } from "alepha/react/head";
+import { type Route, RouterProvider } from "alepha/router";
+import { createElement, type ReactNode } from "react";
+import NotFoundPage from "../components/NotFound.tsx";
+import {
+  isPageRoute,
+  type PageRoute,
+  type PageRouteEntry,
+  type PreviousLayerData,
+  ReactPageProvider,
+  type ReactRouterState,
+} from "./ReactPageProvider.ts";
+
+export interface BrowserRoute extends Route {
+  page: PageRoute;
+}
+
+/**
+ * Implementation of AlephaRouter for React in browser environment.
+ */
+export class ReactBrowserRouterProvider extends RouterProvider<BrowserRoute> {
+  protected readonly log = $logger();
+  protected readonly alepha = $inject(Alepha);
+  protected readonly pageApi = $inject(ReactPageProvider);
+  protected readonly browserHeadProvider = $inject(BrowserHeadProvider);
+
+  public add(entry: PageRouteEntry) {
+    this.pageApi.add(entry);
+  }
+
+  protected readonly configure = $hook({
+    on: "configure",
+    handler: async () => {
+      for (const page of this.pageApi.getPages()) {
+        // mount only if a view is provided
+        if (page.component || page.lazy) {
+          this.push({
+            path: page.match,
+            page,
+          });
+        }
+      }
+    },
+  });
+
+  public async transition(
+    url: URL,
+    previous: PreviousLayerData[] = [],
+    meta = {},
+  ): Promise<string | void> {
+    const { pathname, search } = url;
+
+    const entry: Partial<ReactRouterState> = {
+      url,
+      query: {},
+      params: {},
+      layers: [],
+      onError: () => null,
+      meta,
+    };
+
+    const state = entry as ReactRouterState;
+
+    // Emit both action and transition events
+    await this.alepha.events.emit("react:action:begin", {
+      type: "transition",
+    });
+    await this.alepha.events.emit("react:transition:begin", {
+      previous: this.alepha.store.get("alepha.react.router.state")!,
+      state,
+    });
+
+    try {
+      const { route, params } = this.match(pathname);
+
+      const query: Record<string, string> = {};
+      if (search) {
+        for (const [key, value] of new URLSearchParams(search).entries()) {
+          query[key] = String(value);
+        }
+      }
+
+      state.name = route?.page.name;
+      state.query = query;
+      state.params = params ?? {};
+
+      if (isPageRoute(route)) {
+        const { redirect } = await this.pageApi.createLayers(
+          route.page,
+          state,
+          previous,
+        );
+        if (redirect) {
+          return redirect;
+        }
+      }
+
+      if (state.layers.length === 0) {
+        state.layers.push({
+          name: "not-found",
+          element: createElement(NotFoundPage),
+          index: 0,
+          path: "/",
+        });
+      }
+
+      await this.alepha.events.emit("react:action:success", {
+        type: "transition",
+      });
+      await this.alepha.events.emit("react:transition:success", { state });
+    } catch (e) {
+      this.log.error("Transition has failed", e);
+      state.layers = [
+        {
+          name: "error",
+          element: this.pageApi.renderError(e as Error),
+          index: 0,
+          path: "/",
+        },
+      ];
+
+      await this.alepha.events.emit("react:action:error", {
+        type: "transition",
+        error: e as Error,
+      });
+      await this.alepha.events.emit("react:transition:error", {
+        error: e as Error,
+        state,
+      });
+    }
+
+    // [feature]: local hook for leaving a page
+    if (previous) {
+      for (let i = 0; i < previous.length; i++) {
+        const layer = previous[i];
+        if (state.layers[i]?.name !== layer.name) {
+          this.pageApi.page(layer.name)?.onLeave?.();
+        }
+      }
+    }
+
+    // [feature]: local hook for entering a page
+    for (let i = 0; i < state.layers.length; i++) {
+      const layer = state.layers[i];
+      if (previous?.[i]?.name !== layer.name) {
+        this.pageApi.page(layer.name)?.onEnter?.();
+      }
+    }
+
+    this.alepha.store.set("alepha.react.router.state", state);
+
+    await this.alepha.events.emit("react:action:end", {
+      type: "transition",
+    });
+    await this.alepha.events.emit("react:transition:end", {
+      state,
+    });
+
+    // Fill and render head from route configurations
+    this.browserHeadProvider.fillAndRenderHead(state);
+  }
+
+  public root(state: ReactRouterState): ReactNode {
+    return this.pageApi.root(state);
+  }
+}