alepha 0.15.1 → 0.15.3

package/src/react/core/__tests__/Router.spec.tsx

@@ -0,0 +1,169 @@
+import { Alepha, t } from "alepha";
+import { renderToString } from "react-dom/server";
+import { test } from "vitest";
+import { NestedView } from "../../router/index.ts";
+import { ReactBrowserRouterProvider } from "../../router/providers/ReactBrowserRouterProvider.ts";
+
+const setup = () => {
+  const alepha = Alepha.create();
+  const router = alepha.inject(ReactBrowserRouterProvider);
+
+  const render = async (path: string): Promise<string> => {
+    await router.transition(new URL(`http://localhost${path}`));
+    const state = alepha.store.get("alepha.react.router.state");
+    if (!state) {
+      throw new Error(
+        "Router state not found. Ensure the router is properly configured.",
+      );
+    }
+    const element = router.root(state);
+    return renderToString(element).replaceAll("<!-- -->", "");
+  };
+
+  return {
+    router,
+    render,
+    alepha,
+  };
+};
+
+test("Router - Basic", async ({ expect }) => {
+  const { router, render, alepha } = setup();
+
+  router.add({
+    name: "Test",
+    path: "/",
+    component: () => "Hey",
+  });
+
+  router.add({
+    name: "NotFound",
+    path: "/*",
+    component: () => "Not Found",
+  });
+
+  await alepha.start();
+
+  expect(await render("/")).toEqual("Hey");
+  expect(await render("/zz")).toEqual("Not Found");
+});
+
+test("Router - NestedView", async ({ expect }) => {
+  const { router, render, alepha } = setup();
+
+  router.add({
+    name: "Test",
+    component: () => (
+      <>
+        ((
+        <NestedView />
+        ))
+      </>
+    ),
+    children: [
+      {
+        name: "Home",
+        path: "/",
+        component: () => "Home",
+      },
+      {
+        name: "Hello",
+        path: "/hello/:name",
+        schema: {
+          params: t.object({
+            name: t.text(),
+          }),
+        },
+        loader: ({ params }) => params,
+        component: (props) => `Hello, ${props.name}!`,
+      },
+    ],
+  });
+
+  await alepha.start();
+
+  expect(await render("/")).toEqual("((Home))");
+  expect(await render("/hello/jack")).toEqual("((Hello, jack!))");
+});
+
+test("Router - All routes", async ({ expect }) => {
+  const { router, render, alepha } = setup();
+
+  router.add({
+    children: [
+      {
+        path: "/*",
+        component: () => "404",
+      },
+      {
+        component: () => "home",
+      },
+      {
+        path: "about",
+        component: () => "about",
+      },
+      {
+        path: "sub",
+        children: [
+          {
+            component: () => "a",
+          },
+          {
+            path: "b",
+            component: () => "b",
+          },
+        ],
+      },
+      {
+        path: "users",
+        component: () => <NestedView>yo</NestedView>,
+        children: [
+          {
+            path: "new",
+            component: () => "users/new",
+          },
+          {
+            path: ":id",
+            schema: { params: t.object({ id: t.text() }) },
+            loader: ({ params }) => {
+              if (params.id === "boom") throw new Error("boom");
+              return params;
+            },
+            children: [
+              {
+                loader: ({ params }) => params,
+                component: ({ id }) => `hey ${id}`,
+              },
+              {
+                path: "profile",
+                loader: ({ params }) => params,
+                component: ({ id }) => `profile of ${id}`,
+              },
+            ],
+          },
+        ],
+        errorHandler: (error) => {
+          return `Error: ${error.message}`;
+        },
+      },
+    ],
+  });
+
+  await alepha.start();
+
+  expect(await render("/")).toEqual("home");
+  expect(await render("/about")).toEqual("about");
+  expect(await render("/noop")).toEqual("404");
+  expect(await render("/noop/noop")).toEqual("404");
+  expect(await render("/sub")).toEqual("a");
+  expect(await render("/sub/")).toEqual("a");
+  expect(await render("/sub/b")).toEqual("b");
+  expect(await render("/sub/noop")).toEqual("404");
+  expect(await render("/users")).toEqual("yo");
+  expect(await render("/users/")).toEqual("yo");
+  expect(await render("/users/a")).toEqual("hey a");
+  expect(await render("/users/boom")).toEqual("Error: boom");
+  expect(await render("/users/new")).toEqual("users/new");
+  expect(await render("/users/hey/ho")).toEqual("404");
+  expect(await render("/users/a/profile")).toEqual("profile of a");
+});

package/src/react/core/components/ClientOnly.tsx

@@ -0,0 +1,49 @@
+import {
+  type PropsWithChildren,
+  type ReactNode,
+  useEffect,
+  useState,
+} from "react";
+
+export interface ClientOnlyProps {
+  fallback?: ReactNode;
+  disabled?: boolean;
+}
+
+/**
+ * A small utility component that renders its children only on the client side.
+ *
+ * Optionally, you can provide a fallback React node that will be rendered.
+ *
+ * You should use this component when
+ * - you have code that relies on browser-specific APIs
+ * - you want to avoid server-side rendering for a specific part of your application
+ * - you want to prevent pre-rendering of a component
+ *
+ * @example
+ * ```tsx
+ * import { ClientOnly } from "alepha/react";
+ *
+ * const MyComponent = () => {
+ *   // Avoids SSR issues with Date API
+ *   return (
+ *     <ClientOnly>
+ *       {new Date().toLocaleTimeString()}
+ *     </ClientOnly>
+ *   );
+ * }
+ * ```
+ */
+const ClientOnly = (props: PropsWithChildren<ClientOnlyProps>) => {
+  const [mounted, setMounted] = useState(false);
+
+  useEffect(() => setMounted(true), []);
+
+  if (props.disabled) {
+    return props.children;
+  }
+
+  return mounted ? props.children : props.fallback;
+};
+
+export default ClientOnly;

package/src/react/core/components/ErrorBoundary.tsx

@@ -0,0 +1,73 @@
+import React, {
+  type ErrorInfo,
+  type PropsWithChildren,
+  type ReactNode,
+} from "react";
+
+/**
+ * Props for the ErrorBoundary component.
+ */
+export interface ErrorBoundaryProps {
+  /**
+   * Fallback React node to render when an error is caught.
+   * If not provided, a default error message will be shown.
+   */
+  fallback: (error: Error) => ReactNode;
+
+  /**
+   * Optional callback that receives the error and error info.
+   * Use this to log errors to a monitoring service.
+   */
+  onError?: (error: Error, info: ErrorInfo) => void;
+}
+
+/**
+ * State of the ErrorBoundary component.
+ */
+interface ErrorBoundaryState {
+  error?: Error;
+}
+
+/**
+ * A reusable error boundary for catching rendering errors in any part of the React component tree.
+ *
+ * It's already included in the Alepha React framework when using page or layout components.
+ */
+export class ErrorBoundary extends React.Component<
+  PropsWithChildren<ErrorBoundaryProps>,
+  ErrorBoundaryState
+> {
+  constructor(props: ErrorBoundaryProps) {
+    super(props);
+    this.state = {};
+  }
+
+  /**
+   * Update state so the next render shows the fallback UI.
+   */
+  static getDerivedStateFromError(error: Error): ErrorBoundaryState {
+    return {
+      error,
+    };
+  }
+
+  /**
+   * Lifecycle method called when an error is caught.
+   * You can log the error or perform side effects here.
+   */
+  componentDidCatch(error: Error, info: ErrorInfo): void {
+    if (this.props.onError) {
+      this.props.onError(error, info);
+    }
+  }
+
+  render(): ReactNode {
+    if (this.state.error) {
+      return this.props.fallback(this.state.error);
+    }
+
+    return this.props.children;
+  }
+}
+
+export default ErrorBoundary;

package/src/react/core/contexts/AlephaContext.ts

@@ -0,0 +1,7 @@
+import type { Alepha } from "alepha";
+import { createContext } from "react";
+
+/**
+ * React context to provide the Alepha instance throughout the component tree.
+ */
+export const AlephaContext = createContext<Alepha | undefined>(undefined);

package/src/react/core/contexts/AlephaProvider.tsx

@@ -0,0 +1,42 @@
+import { Alepha } from "alepha";
+import { type ReactNode, useEffect, useMemo, useState } from "react";
+import { AlephaContext } from "./AlephaContext.ts";
+
+export interface AlephaProviderProps {
+  children: ReactNode;
+  onError: (error: Error) => ReactNode;
+  onLoading: () => ReactNode;
+}
+
+/**
+ * AlephaProvider component to initialize and provide Alepha instance to the app.
+ *
+ * This isn't recommended for apps using `alepha/react/router`, as Router will handle this for you.
+ */
+export const AlephaProvider = (props: AlephaProviderProps) => {
+  const alepha = useMemo(() => Alepha.create(), []);
+
+  const [started, setStarted] = useState(false);
+  const [error, setError] = useState<Error | undefined>();
+
+  useEffect(() => {
+    alepha
+      .start()
+      .then(() => setStarted(true))
+      .catch((err) => setError(err));
+  }, [alepha]);
+
+  if (error) {
+    return props.onError(error);
+  }
+
+  if (!started) {
+    return props.onLoading();
+  }
+
+  return (
+    <AlephaContext.Provider value={alepha}>
+      {props.children}
+    </AlephaContext.Provider>
+  );
+};