alepha 0.15.0 → 0.15.2

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>
+  );
+};