alepha 0.15.1 → 0.15.3

package/src/react/router/components/Link.tsx

@@ -0,0 +1,23 @@
+import { type AnchorHTMLAttributes, createElement } from "react";
+import { useRouter } from "../hooks/useRouter.ts";
+
+export interface LinkProps extends AnchorHTMLAttributes<HTMLAnchorElement> {
+  href: string;
+}
+
+/**
+ * Link component for client-side navigation.
+ *
+ * It's a simple wrapper around an anchor (`<a>`) element using the `useRouter` hook.
+ */
+const Link = (props: LinkProps) => {
+  const router = useRouter();
+
+  return createElement(
+    "a",
+    { ...props, ...router.anchor(props.href) },
+    props.children,
+  );
+};
+
+export default Link;

package/src/react/router/components/NestedView.tsx

@@ -0,0 +1,223 @@
+import { ErrorBoundary, useAlepha, useEvents } from "alepha/react";
+import { memo, type ReactNode, use, useRef, useState } from "react";
+import { RouterLayerContext } from "../contexts/RouterLayerContext.ts";
+import { Redirection } from "../errors/Redirection.ts";
+import { useRouterState } from "../hooks/useRouterState.ts";
+import type { PageAnimation } from "../primitives/$page.ts";
+import type { ReactRouterState } from "../providers/ReactPageProvider.ts";
+import ErrorViewer from "./ErrorViewer.tsx";
+
+export interface NestedViewProps {
+  children?: ReactNode;
+  errorBoundary?: false | ((error: Error) => ReactNode);
+}
+
+/**
+ * A component that renders the current view of the nested router layer.
+ *
+ * To be simple, it renders the `element` of the current child page of a parent page.
+ *
+ * @example
+ * ```tsx
+ * import { NestedView } from "alepha/react";
+ *
+ * class App {
+ *   parent = $page({
+ *     component: () => <NestedView />,
+ *   });
+ *
+ *   child = $page({
+ *     parent: this.root,
+ *     component: () => <div>Child Page</div>,
+ *   });
+ * }
+ * ```
+ */
+const NestedView = (props: NestedViewProps) => {
+  const routerLayer = use(RouterLayerContext);
+  const index = routerLayer?.index ?? 0;
+  const onError = routerLayer?.onError;
+  const state = useRouterState();
+  const alepha = useAlepha();
+
+  const [view, setView] = useState<ReactNode | undefined>(
+    state.layers[index]?.element,
+  );
+
+  const [animation, setAnimation] = useState("");
+  const animationExitDuration = useRef<number>(0);
+  const animationExitNow = useRef<number>(0);
+
+  useEvents(
+    {
+      "react:transition:begin": async ({ previous, state }) => {
+        // --------- Animations Begin ---------
+        const layer = previous.layers[index];
+        if (!layer) {
+          return;
+        }
+
+        if (`${state.url.pathname}/`.startsWith(`${layer.path}/`)) {
+          return;
+        }
+
+        const animationExit = parseAnimation(
+          layer.route?.animation,
+          state,
+          "exit",
+        );
+
+        if (animationExit) {
+          const duration = animationExit.duration || 200;
+          animationExitNow.current = Date.now();
+          animationExitDuration.current = duration;
+          setAnimation(animationExit.animation);
+        } else {
+          animationExitNow.current = 0;
+          animationExitDuration.current = 0;
+          setAnimation("");
+        }
+        // --------- Animations End ---------
+      },
+      "react:transition:end": async ({ state }) => {
+        const layer = state.layers[index];
+
+        // --------- Animations Begin ---------
+        if (animationExitNow.current) {
+          const duration = animationExitDuration.current;
+          const diff = Date.now() - animationExitNow.current;
+          if (diff < duration) {
+            await new Promise((resolve) =>
+              setTimeout(resolve, duration - diff),
+            );
+          }
+        }
+        // --------- Animations End ---------
+
+        if (!layer?.cache) {
+          setView(layer?.element);
+
+          // --------- Animations Begin ---------
+          const animationEnter = parseAnimation(
+            layer?.route?.animation,
+            state,
+            "enter",
+          );
+
+          if (animationEnter) {
+            setAnimation(animationEnter.animation);
+          } else {
+            setAnimation("");
+          }
+          // --------- Animations End ---------
+        }
+      },
+    },
+    [],
+  );
+
+  let element = view ?? props.children ?? null;
+
+  // --------- Animations Begin ---------
+  if (animation) {
+    element = (
+      <div
+        style={{
+          display: "flex",
+          flex: 1,
+          height: "100%",
+          width: "100%",
+          position: "relative",
+          overflow: "hidden",
+        }}
+      >
+        <div
+          style={{ height: "100%", width: "100%", display: "flex", animation }}
+        >
+          {element}
+        </div>
+      </div>
+    );
+  }
+  // --------- Animations End ---------
+
+  if (props.errorBoundary === false) {
+    return <>{element}</>;
+  }
+
+  if (props.errorBoundary) {
+    return (
+      <ErrorBoundary fallback={props.errorBoundary}>{element}</ErrorBoundary>
+    );
+  }
+
+  const fallback = (error: Error) => {
+    const result = onError?.(error, state) ?? (
+      <ErrorViewer error={error} alepha={alepha} />
+    );
+    if (result instanceof Redirection) {
+      return "Redirection inside ErrorBoundary is not allowed.";
+    }
+    return result as ReactNode;
+  };
+
+  return <ErrorBoundary fallback={fallback}>{element}</ErrorBoundary>;
+};
+
+export default memo(NestedView);
+
+function parseAnimation(
+  animationLike: PageAnimation | undefined,
+  state: ReactRouterState,
+  type: "enter" | "exit" = "enter",
+):
+  | {
+      duration: number;
+      animation: string;
+    }
+  | undefined {
+  if (!animationLike) {
+    return undefined;
+  }
+
+  const DEFAULT_DURATION = 300;
+
+  const animation =
+    typeof animationLike === "function" ? animationLike(state) : animationLike;
+
+  if (typeof animation === "string") {
+    if (type === "exit") {
+      return;
+    }
+    return {
+      duration: DEFAULT_DURATION,
+      animation: `${DEFAULT_DURATION}ms ${animation}`,
+    };
+  }
+
+  if (typeof animation === "object") {
+    const anim = animation[type];
+    const duration =
+      typeof anim === "object"
+        ? (anim.duration ?? DEFAULT_DURATION)
+        : DEFAULT_DURATION;
+    const name = typeof anim === "object" ? anim.name : anim;
+
+    if (type === "exit") {
+      const timing = typeof anim === "object" ? (anim.timing ?? "") : "";
+      return {
+        duration,
+        animation: `${duration}ms ${timing} ${name}`,
+      };
+    }
+
+    const timing = typeof anim === "object" ? (anim.timing ?? "") : "";
+
+    return {
+      duration,
+      animation: `${duration}ms ${timing} ${name}`,
+    };
+  }
+
+  return undefined;
+}

package/src/react/router/components/NotFound.tsx

@@ -0,0 +1,30 @@
+import type { CSSProperties } from "react";
+
+/**
+ * Default 404 Not Found page component.
+ */
+const NotFound = (props: { style?: CSSProperties }) => (
+  <div
+    style={{
+      width: "100%",
+      minHeight: "90vh",
+      boxSizing: "border-box",
+      display: "flex",
+      flexDirection: "column",
+      justifyContent: "center",
+      alignItems: "center",
+      textAlign: "center",
+      fontFamily:
+        'system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif',
+      padding: "2rem",
+      ...props.style,
+    }}
+  >
+    <div style={{ fontSize: "6rem", fontWeight: 200, lineHeight: 1 }}>404</div>
+    <div style={{ fontSize: "0.875rem", marginTop: "1rem", opacity: 0.6 }}>
+      Page not found
+    </div>
+  </div>
+);
+
+export default NotFound;

package/src/react/router/constants/PAGE_PRELOAD_KEY.ts

@@ -0,0 +1,6 @@
+/**
+ * Symbol key for SSR module preloading path.
+ * Using Symbol.for() allows the Vite plugin to inject this at build time.
+ * @internal
+ */
+export const PAGE_PRELOAD_KEY = Symbol.for("alepha.page.preload");

package/src/react/router/contexts/RouterLayerContext.ts

@@ -0,0 +1,12 @@
+import { createContext } from "react";
+import type { ErrorHandler } from "../primitives/$page.ts";
+
+export interface RouterLayerContextValue {
+  index: number;
+  path: string;
+  onError: ErrorHandler;
+}
+
+export const RouterLayerContext = createContext<
+  RouterLayerContextValue | undefined
+>(undefined);

package/src/react/router/errors/Redirection.ts

@@ -0,0 +1,28 @@
+import { AlephaError } from "alepha";
+
+/**
+ * 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({
+ *   loader: async () => {
+ *    if (needRedirect) {
+ *      throw new Redirection("/new-path");
+ *    }
+ *   },
+ * });
+ * ```
+ */
+export class Redirection extends AlephaError {
+  public readonly redirect: string;
+
+  constructor(redirect: string) {
+    super("Redirection");
+    this.redirect = redirect;
+  }
+}

package/src/react/router/hooks/useActive.ts

@@ -0,0 +1,52 @@
+import { useState } from "react";
+import type { AnchorProps } from "../providers/ReactPageProvider.ts";
+import { useRouter } from "./useRouter.ts";
+import { useRouterState } from "./useRouterState.ts";
+
+export interface UseActiveOptions {
+  href: string;
+  startWith?: boolean;
+}
+
+/**
+ * Hook to determine if a given route is active and to provide anchor props for navigation.
+ * This hook refreshes on router state changes.
+ */
+export const useActive = (args: string | UseActiveOptions): UseActiveHook => {
+  useRouterState();
+
+  const router = useRouter();
+  const [isPending, setPending] = useState(false);
+
+  const options: UseActiveOptions =
+    typeof args === "string" ? { href: args } : { ...args, href: args.href };
+  const href = options.href;
+  const isActive = router.isActive(href, options);
+
+  return {
+    isPending,
+    isActive,
+    anchorProps: {
+      href: router.base(href),
+      onClick: async (ev?: any) => {
+        ev?.stopPropagation();
+        ev?.preventDefault();
+        if (isActive) return;
+        if (isPending) return;
+
+        setPending(true);
+        try {
+          await router.push(href);
+        } finally {
+          setPending(false);
+        }
+      },
+    },
+  };
+};
+
+export interface UseActiveHook {
+  isActive: boolean;
+  anchorProps: AnchorProps;
+  isPending: boolean;
+}

package/src/react/router/hooks/useQueryParams.ts

@@ -0,0 +1,63 @@
+import type { Alepha, Static, TObject } from "alepha";
+import { useAlepha } from "alepha/react";
+import { useEffect, useState } from "react";
+import { useRouter } from "./useRouter.ts";
+
+/**
+ * Hook to manage query parameters in the URL using a defined schema.
+ */
+export const useQueryParams = <T extends TObject>(
+  schema: T,
+  options: UseQueryParamsHookOptions = {},
+): [Partial<Static<T>>, (data: Static<T>) => void] => {
+  const alepha = useAlepha();
+
+  const key = options.key ?? "q";
+  const router = useRouter();
+  const querystring = router.query[key];
+
+  const [queryParams = {}, setQueryParams] = useState<Static<T> | undefined>(
+    decode(alepha, schema, router.query[key]),
+  );
+
+  useEffect(() => {
+    setQueryParams(decode(alepha, schema, querystring));
+  }, [querystring]);
+
+  return [
+    queryParams,
+    (queryParams: Static<T>) => {
+      setQueryParams(queryParams);
+      router.setQueryParams((data) => {
+        return { ...data, [key]: encode(alepha, schema, queryParams) };
+      });
+    },
+  ];
+};
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+export interface UseQueryParamsHookOptions {
+  format?: "base64" | "querystring";
+  key?: string;
+  push?: boolean;
+}
+
+const encode = (alepha: Alepha, schema: TObject, data: any) => {
+  return btoa(JSON.stringify(alepha.codec.decode(schema, data)));
+};
+
+const decode = <T extends TObject>(
+  alepha: Alepha,
+  schema: T,
+  data: any,
+): Static<T> | undefined => {
+  try {
+    return alepha.codec.decode(
+      schema,
+      JSON.parse(atob(decodeURIComponent(data))),
+    );
+  } catch {
+    return;
+  }
+};

package/src/react/router/hooks/useRouter.ts

@@ -0,0 +1,20 @@
+import { useInject } from "alepha/react";
+import { ReactRouter } from "../services/ReactRouter.ts";
+
+/**
+ * Use this hook to access the React Router instance.
+ *
+ * You can add a type parameter to specify the type of your application.
+ * This will allow you to use the router in a typesafe way.
+ *
+ * @example
+ * class App {
+ *   home = $page();
+ * }
+ *
+ * const router = useRouter<App>();
+ * router.push("home"); // typesafe
+ */
+export const useRouter = <T extends object = any>(): ReactRouter<T> => {
+  return useInject(ReactRouter<T>);
+};

package/src/react/router/hooks/useRouterState.ts

@@ -0,0 +1,11 @@
+import { AlephaError } from "alepha";
+import { useStore } from "alepha/react";
+import type { ReactRouterState } from "../providers/ReactPageProvider.ts";
+
+export const useRouterState = (): ReactRouterState => {
+  const [state] = useStore("alepha.react.router.state");
+  if (!state) {
+    throw new AlephaError("Missing react router state");
+  }
+  return state;
+};

package/src/react/router/index.browser.ts

@@ -0,0 +1,45 @@
+import { $module } from "alepha";
+import { AlephaDateTime } from "alepha/datetime";
+import { AlephaReact } from "alepha/react";
+import { AlephaServer } from "alepha/server";
+import { AlephaServerLinks } from "alepha/server/links";
+import { $page } from "./primitives/$page.ts";
+import { ReactBrowserProvider } from "./providers/ReactBrowserProvider.ts";
+import { ReactBrowserRendererProvider } from "./providers/ReactBrowserRendererProvider.ts";
+import { ReactBrowserRouterProvider } from "./providers/ReactBrowserRouterProvider.ts";
+import { ReactPageProvider } from "./providers/ReactPageProvider.ts";
+import { ReactPageService } from "./services/ReactPageService.ts";
+import { ReactRouter } from "./services/ReactRouter.ts";
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+export * from "./index.shared.ts";
+export * from "./providers/ReactBrowserProvider.ts";
+export * from "./providers/ReactBrowserRendererProvider.ts";
+export * from "./providers/ReactBrowserRouterProvider.ts";
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+export const AlephaReactRouter = $module({
+  name: "alepha.react.router",
+  primitives: [$page],
+  services: [
+    ReactPageProvider,
+    ReactBrowserRouterProvider,
+    ReactBrowserProvider,
+    ReactRouter,
+    ReactBrowserRendererProvider,
+    ReactPageService,
+  ],
+  register: (alepha) =>
+    alepha
+      .with(AlephaReact)
+      .with(AlephaDateTime)
+      .with(AlephaServer)
+      .with(AlephaServerLinks)
+      .with(ReactPageProvider)
+      .with(ReactBrowserProvider)
+      .with(ReactBrowserRouterProvider)
+      .with(ReactBrowserRendererProvider)
+      .with(ReactRouter),
+});

package/src/react/router/index.shared.ts

@@ -0,0 +1,19 @@
+export type * from "./components/ErrorViewer.tsx";
+export { default as ErrorViewer } from "./components/ErrorViewer.tsx";
+export type * from "./components/Link.tsx";
+export { default as Link, type LinkProps } from "./components/Link.tsx";
+export type * from "./components/NestedView.tsx";
+export { default as NestedView } from "./components/NestedView.tsx";
+export type * from "./components/NotFound.tsx";
+export { default as NotFound } from "./components/NotFound.tsx";
+export * from "./constants/PAGE_PRELOAD_KEY.ts";
+export * from "./contexts/RouterLayerContext.ts";
+export * from "./errors/Redirection.ts";
+export * from "./hooks/useActive.ts";
+export * from "./hooks/useQueryParams.ts";
+export * from "./hooks/useRouter.ts";
+export * from "./hooks/useRouterState.ts";
+export * from "./primitives/$page.ts";
+export * from "./providers/ReactPageProvider.ts";
+export * from "./services/ReactPageService.ts";
+export * from "./services/ReactRouter.ts";

package/src/react/router/index.ts

@@ -0,0 +1,146 @@
+import { $module } from "alepha";
+import { AlephaDateTime } from "alepha/datetime";
+import { AlephaReact } from "alepha/react";
+import { AlephaServer, type ServerRequest } from "alepha/server";
+import { AlephaServerCache } from "alepha/server/cache";
+import { AlephaServerLinks } from "alepha/server/links";
+import type { ReactNode } from "react";
+import { $page, type PageAnimation } from "./primitives/$page.ts";
+import type { ReactHydrationState } from "./providers/ReactBrowserProvider.ts";
+import {
+  ReactPageProvider,
+  type ReactRouterState,
+} from "./providers/ReactPageProvider.ts";
+import { ReactPreloadProvider } from "./providers/ReactPreloadProvider.ts";
+import { ReactServerProvider } from "./providers/ReactServerProvider.ts";
+import { ReactServerTemplateProvider } from "./providers/ReactServerTemplateProvider.ts";
+import { SSRManifestProvider } from "./providers/SSRManifestProvider.ts";
+import { ReactPageServerService } from "./services/ReactPageServerService.ts";
+import { ReactPageService } from "./services/ReactPageService.ts";
+import { ReactRouter } from "./services/ReactRouter.ts";
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+export * from "./index.shared.ts";
+export * from "./providers/ReactBrowserProvider.ts";
+export * from "./providers/ReactPageProvider.ts";
+export * from "./providers/ReactPreloadProvider.ts";
+export * from "./providers/ReactServerProvider.ts";
+export * from "./providers/ReactServerTemplateProvider.ts";
+export * from "./providers/SSRManifestProvider.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.
+     *
+     * Note: this one is not really necessary, it's a hack because we need to isolate renderer from server code in order
+     * to avoid including react-dom/client in server bundles.
+     */
+    "react:browser:render": {
+      root: HTMLElement;
+      element: ReactNode;
+      state: ReactRouterState;
+      hydration?: ReactHydrationState;
+    };
+    // -----------------------------------------------------------------------------------------------------------------
+    // SPECIFIC: Route transitions
+    /**
+     * 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 `loader` function
+ * - Lazy loading and code splitting
+ * - Page animations and error handling
+ *
+ * @see {@link $page}
+ * @module alepha.react.router
+ */
+export const AlephaReactRouter = $module({
+  name: "alepha.react.router",
+  primitives: [$page],
+  services: [
+    ReactPageProvider,
+    ReactPageService,
+    ReactPreloadProvider,
+    ReactRouter,
+    ReactServerProvider,
+    ReactServerTemplateProvider,
+    SSRManifestProvider,
+    ReactPageServerService,
+  ],
+  register: (alepha) =>
+    alepha
+      .with(AlephaReact)
+      .with(AlephaDateTime)
+      .with(AlephaServer)
+      .with(AlephaServerCache)
+      .with(AlephaServerLinks)
+      .with({
+        provide: ReactPageService,
+        use: ReactPageServerService,
+      })
+      .with(SSRManifestProvider)
+      .with(ReactServerTemplateProvider)
+      .with(ReactPreloadProvider)
+      .with(ReactServerProvider)
+      .with(ReactPageProvider)
+      .with(ReactRouter),
+});