@alepha/react 0.13.6 → 0.13.8

package/src/core/components/ErrorViewer.tsx

@@ -1,163 +1,411 @@
 import type { Alepha } from "alepha";
-import { useState } from "react";
+import { type CSSProperties, useState } from "react";
 
 interface ErrorViewerProps {
   error: Error;
   alepha: Alepha;
 }
 
-// TODO: design this better
+interface StackFrame {
+  fn: string;
+  file: string;
+  line: string;
+  col: string;
+  raw: string;
+}
 
+/**
+ * Error viewer component that displays error details in development mode
+ */
 const ErrorViewer = ({ error, alepha }: ErrorViewerProps) => {
   const [expanded, setExpanded] = useState(false);
   const isProduction = alepha.isProduction();
-  // const status = isHttpError(error) ? error.status : 500;
 
   if (isProduction) {
     return <ErrorViewerProduction />;
   }
 
-  const stackLines = error.stack?.split("\n") ?? [];
-  const previewLines = stackLines.slice(0, 5);
-  const hiddenLineCount = stackLines.length - previewLines.length;
+  const frames = parseStackTrace(error.stack);
+  const visibleFrames = expanded ? frames : frames.slice(0, 6);
+  const hiddenCount = frames.length - 6;
 
-  const copyToClipboard = (text: string) => {
-    navigator.clipboard.writeText(text).catch((err) => {
-      console.error("Clipboard error:", err);
-    });
-  };
+  return (
+    <div style={styles.overlay}>
+      <div style={styles.container}>
+        <Header error={error} />
+        <StackTraceSection
+          frames={frames}
+          visibleFrames={visibleFrames}
+          expanded={expanded}
+          hiddenCount={hiddenCount}
+          onToggle={() => setExpanded(!expanded)}
+        />
+      </div>
+    </div>
+  );
+};
+
+export default ErrorViewer;
+
+/**
+ * Parse stack trace string into structured frames
+ */
+function parseStackTrace(stack?: string): StackFrame[] {
+  if (!stack) return [];
+
+  const lines = stack.split("\n").slice(1);
+  const frames: StackFrame[] = [];
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith("at ")) continue;
+
+    const frame = parseStackLine(trimmed);
+    if (frame) frames.push(frame);
+  }
+
+  return frames;
+}
+
+/**
+ * Parse a single stack trace line into a structured frame
+ */
+function parseStackLine(line: string): StackFrame | null {
+  const withFn = line.match(/^at\s+(.+?)\s+\((.+):(\d+):(\d+)\)$/);
+  if (withFn) {
+    return {
+      fn: withFn[1],
+      file: withFn[2],
+      line: withFn[3],
+      col: withFn[4],
+      raw: line,
+    };
+  }
+
+  const withoutFn = line.match(/^at\s+(.+):(\d+):(\d+)$/);
+  if (withoutFn) {
+    return {
+      fn: "<anonymous>",
+      file: withoutFn[1],
+      line: withoutFn[2],
+      col: withoutFn[3],
+      raw: line,
+    };
+  }
+
+  return { fn: "", file: line.replace(/^at\s+/, ""), line: "", col: "", raw: line };
+}
+
+/**
+ * Copy text to clipboard
+ */
+function copyToClipboard(text: string): void {
+  navigator.clipboard.writeText(text).catch((err) => {
+    console.error("Clipboard error:", err);
+  });
+}
+
+/**
+ * Header section with error type and message
+ */
+function Header({ error }: { error: Error }) {
+  const [copied, setCopied] = useState(false);
 
-  const styles = {
-    container: {
-      padding: "24px",
-      backgroundColor: "#FEF2F2",
-      color: "#7F1D1D",
-      border: "1px solid #FECACA",
-      borderRadius: "16px",
-      boxShadow: "0 8px 24px rgba(0,0,0,0.05)",
-      fontFamily: "monospace",
-      maxWidth: "768px",
-      margin: "40px auto",
-    },
-    heading: {
-      fontSize: "20px",
-      fontWeight: "bold",
-      marginBottom: "10px",
-    },
-    name: {
-      fontSize: "16px",
-      fontWeight: 600,
-    },
-    message: {
-      fontSize: "14px",
-      marginBottom: "16px",
-    },
-    sectionHeader: {
-      display: "flex",
-      justifyContent: "space-between",
-      alignItems: "center",
-      fontSize: "12px",
-      marginBottom: "4px",
-      color: "#991B1B",
-    },
-    copyButton: {
-      fontSize: "12px",
-      color: "#DC2626",
-      background: "none",
-      border: "none",
-      cursor: "pointer",
-      textDecoration: "underline",
-    },
-    stackContainer: {
-      backgroundColor: "#FEE2E2",
-      padding: "12px",
-      borderRadius: "8px",
-      fontSize: "13px",
-      lineHeight: "1.4",
-      overflowX: "auto" as const,
-      whiteSpace: "pre-wrap" as const,
-    },
-    expandLine: {
-      color: "#F87171",
-      cursor: "pointer",
-      marginTop: "8px",
-    },
+  const handleCopy = () => {
+    copyToClipboard(error.stack || error.message);
+    setCopied(true);
+    setTimeout(() => setCopied(false), 2000);
   };
 
   return (
-    <div style={styles.container}>
-      <div>
-        <div style={styles.heading}>🔥 Error</div>
-        <div style={styles.name}>{error.name}</div>
-        <div style={styles.message}>{error.message}</div>
+    <div style={styles.header}>
+      <div style={styles.headerTop}>
+        <div style={styles.badge}>{error.name}</div>
+        <button type="button" onClick={handleCopy} style={styles.copyBtn}>
+          {copied ? "Copied" : "Copy Stack"}
+        </button>
       </div>
+      <h1 style={styles.message}>{error.message}</h1>
+    </div>
+  );
+}
 
-      {stackLines.length > 0 && (
-        <div>
-          <div style={styles.sectionHeader}>
-            <span>Stack trace</span>
-            <button
-              type="button"
-              onClick={() => copyToClipboard(error.stack!)}
-              style={styles.copyButton}
-            >
-              Copy all
-            </button>
-          </div>
-          <pre style={styles.stackContainer}>
-            {(expanded ? stackLines : previewLines).map((line, i) => (
-              <div key={i}>{line}</div>
-            ))}
-            {!expanded && hiddenLineCount > 0 && (
-              <div  style={styles.expandLine} onClick={() => setExpanded(true)}>
-                + {hiddenLineCount} more lines...
-              </div>
-            )}
-          </pre>
-        </div>
-      )}
+/**
+ * Stack trace section with expandable frames
+ */
+function StackTraceSection({
+  frames,
+  visibleFrames,
+  expanded,
+  hiddenCount,
+  onToggle,
+}: {
+  frames: StackFrame[];
+  visibleFrames: StackFrame[];
+  expanded: boolean;
+  hiddenCount: number;
+  onToggle: () => void;
+}) {
+  if (frames.length === 0) return null;
+
+  return (
+    <div style={styles.stackSection}>
+      <div style={styles.stackHeader}>Call Stack</div>
+      <div style={styles.frameList}>
+        {visibleFrames.map((frame, i) => (
+          <StackFrameRow key={i} frame={frame} index={i} />
+        ))}
+        {!expanded && hiddenCount > 0 && (
+          <button type="button" onClick={onToggle} style={styles.expandBtn}>
+            Show {hiddenCount} more frames
+          </button>
+        )}
+        {expanded && hiddenCount > 0 && (
+          <button type="button" onClick={onToggle} style={styles.expandBtn}>
+            Show less
+          </button>
+        )}
+      </div>
     </div>
   );
-};
+}
 
-export default ErrorViewer;
+/**
+ * Single stack frame row
+ */
+function StackFrameRow({ frame, index }: { frame: StackFrame; index: number }) {
+  const isFirst = index === 0;
+  const fileName = frame.file.split("/").pop() || frame.file;
+  const dirPath = frame.file.substring(0, frame.file.length - fileName.length);
 
-const ErrorViewerProduction = () => {
-  const styles = {
-    container: {
-      padding: "24px",
-      backgroundColor: "#FEF2F2",
-      color: "#7F1D1D",
-      border: "1px solid #FECACA",
-      borderRadius: "16px",
-      boxShadow: "0 8px 24px rgba(0,0,0,0.05)",
-      fontFamily: "monospace",
-      maxWidth: "768px",
-      margin: "40px auto",
-      textAlign: "center" as const,
-    },
-    heading: {
-      fontSize: "20px",
-      fontWeight: "bold",
-      marginBottom: "8px",
-    },
-    name: {
-      fontSize: "16px",
-      fontWeight: 600,
-      marginBottom: "4px",
-    },
-    message: {
-      fontSize: "14px",
-      opacity: 0.85,
-    },
-  };
+  return (
+    <div
+      style={{
+        ...styles.frame,
+        ...(isFirst ? styles.frameFirst : {}),
+      }}
+    >
+      <div style={styles.frameIndex}>{index + 1}</div>
+      <div style={styles.frameContent}>
+        {frame.fn && (
+          <div style={styles.fnName}>
+            {frame.fn}
+          </div>
+        )}
+        <div style={styles.filePath}>
+          <span style={styles.dirPath}>{dirPath}</span>
+          <span style={styles.fileName}>{fileName}</span>
+          {frame.line && (
+            <span style={styles.lineCol}>
+              :{frame.line}:{frame.col}
+            </span>
+          )}
+        </div>
+      </div>
+    </div>
+  );
+}
 
+/**
+ * Production error view - minimal information
+ */
+function ErrorViewerProduction() {
   return (
-    <div style={styles.container}>
-      <div style={styles.heading}>🚨 An error occurred</div>
-      <div style={styles.message}>
-        Something went wrong. Please try again later.
+    <div style={styles.overlay}>
+      <div style={styles.prodContainer}>
+        <div style={styles.prodIcon}>!</div>
+        <h1 style={styles.prodTitle}>Application Error</h1>
+        <p style={styles.prodMessage}>
+          An unexpected error occurred. Please try again later.
+        </p>
+        <button
+          type="button"
+          onClick={() => window.location.reload()}
+          style={styles.prodButton}
+        >
+          Reload Page
+        </button>
       </div>
     </div>
   );
+}
+
+const styles: Record<string, CSSProperties> = {
+  overlay: {
+    position: "fixed",
+    inset: 0,
+    backgroundColor: "rgba(0, 0, 0, 0.8)",
+    display: "flex",
+    alignItems: "flex-start",
+    justifyContent: "center",
+    padding: "40px 20px",
+    overflow: "auto",
+    fontFamily:
+      '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif',
+    zIndex: 99999,
+  },
+  container: {
+    width: "100%",
+    maxWidth: "960px",
+    backgroundColor: "#1a1a1a",
+    borderRadius: "12px",
+    overflow: "hidden",
+    boxShadow: "0 25px 50px -12px rgba(0, 0, 0, 0.5)",
+  },
+  header: {
+    padding: "24px 28px",
+    borderBottom: "1px solid #333",
+    background: "linear-gradient(to bottom, #1f1f1f, #1a1a1a)",
+  },
+  headerTop: {
+    display: "flex",
+    alignItems: "center",
+    justifyContent: "space-between",
+    marginBottom: "16px",
+  },
+  badge: {
+    display: "inline-block",
+    padding: "6px 12px",
+    backgroundColor: "#dc2626",
+    color: "#fff",
+    fontSize: "12px",
+    fontWeight: 600,
+    borderRadius: "6px",
+    letterSpacing: "0.025em",
+  },
+  copyBtn: {
+    padding: "8px 16px",
+    backgroundColor: "transparent",
+    color: "#888",
+    fontSize: "13px",
+    fontWeight: 500,
+    border: "1px solid #444",
+    borderRadius: "6px",
+    cursor: "pointer",
+    transition: "all 0.15s",
+  },
+  message: {
+    margin: 0,
+    fontSize: "20px",
+    fontWeight: 500,
+    color: "#fff",
+    lineHeight: 1.5,
+    wordBreak: "break-word",
+  },
+  stackSection: {
+    padding: "0",
+  },
+  stackHeader: {
+    padding: "16px 28px",
+    fontSize: "11px",
+    fontWeight: 600,
+    color: "#666",
+    textTransform: "uppercase",
+    letterSpacing: "0.1em",
+    borderBottom: "1px solid #2a2a2a",
+  },
+  frameList: {
+    display: "flex",
+    flexDirection: "column",
+  },
+  frame: {
+    display: "flex",
+    alignItems: "flex-start",
+    padding: "14px 28px",
+    borderBottom: "1px solid #252525",
+    transition: "background-color 0.15s",
+  },
+  frameFirst: {
+    backgroundColor: "rgba(220, 38, 38, 0.1)",
+  },
+  frameIndex: {
+    width: "28px",
+    flexShrink: 0,
+    fontSize: "12px",
+    fontWeight: 500,
+    color: "#555",
+    fontFamily: "monospace",
+  },
+  frameContent: {
+    flex: 1,
+    minWidth: 0,
+  },
+  fnName: {
+    fontSize: "14px",
+    fontWeight: 500,
+    color: "#e5e5e5",
+    marginBottom: "4px",
+    fontFamily:
+      'ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, monospace',
+  },
+  filePath: {
+    fontSize: "13px",
+    color: "#888",
+    fontFamily:
+      'ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, monospace',
+    wordBreak: "break-all",
+  },
+  dirPath: {
+    color: "#555",
+  },
+  fileName: {
+    color: "#0ea5e9",
+  },
+  lineCol: {
+    color: "#eab308",
+  },
+  expandBtn: {
+    padding: "16px 28px",
+    backgroundColor: "transparent",
+    color: "#666",
+    fontSize: "13px",
+    fontWeight: 500,
+    border: "none",
+    borderTop: "1px solid #252525",
+    cursor: "pointer",
+    textAlign: "left",
+    transition: "all 0.15s",
+  },
+  prodContainer: {
+    textAlign: "center",
+    padding: "60px 40px",
+    backgroundColor: "#1a1a1a",
+    borderRadius: "12px",
+    maxWidth: "400px",
+  },
+  prodIcon: {
+    width: "64px",
+    height: "64px",
+    margin: "0 auto 24px",
+    backgroundColor: "#dc2626",
+    borderRadius: "50%",
+    display: "flex",
+    alignItems: "center",
+    justifyContent: "center",
+    fontSize: "32px",
+    fontWeight: 700,
+    color: "#fff",
+  },
+  prodTitle: {
+    margin: "0 0 12px",
+    fontSize: "24px",
+    fontWeight: 600,
+    color: "#fff",
+  },
+  prodMessage: {
+    margin: "0 0 28px",
+    fontSize: "15px",
+    color: "#888",
+    lineHeight: 1.6,
+  },
+  prodButton: {
+    padding: "12px 24px",
+    backgroundColor: "#fff",
+    color: "#000",
+    fontSize: "14px",
+    fontWeight: 600,
+    border: "none",
+    borderRadius: "8px",
+    cursor: "pointer",
+  },
 };

package/src/core/components/NestedView.tsx

@@ -1,11 +1,13 @@
 import { memo, type ReactNode, use, useRef, useState } from "react";
 import { RouterLayerContext } from "../contexts/RouterLayerContext.ts";
-import type { PageAnimation } from "../primitives/$page.ts";
+import type { ErrorHandler, PageAnimation } from "../primitives/$page.ts";
 import { Redirection } from "../errors/Redirection.ts";
 import { useEvents } from "../hooks/useEvents.ts";
 import { useRouterState } from "../hooks/useRouterState.ts";
 import type { ReactRouterState } from "../providers/ReactPageProvider.ts";
 import ErrorBoundary from "./ErrorBoundary.tsx";
+import ErrorViewer from "./ErrorViewer.tsx";
+import { useAlepha } from "../hooks/useAlepha.ts";
 
 export interface NestedViewProps {
   children?: ReactNode;
@@ -34,8 +36,11 @@ export interface NestedViewProps {
  * ```
  */
 const NestedView = (props: NestedViewProps) => {
-  const index = use(RouterLayerContext)?.index ?? 0;
+  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,
@@ -148,16 +153,16 @@ const NestedView = (props: NestedViewProps) => {
     );
   }
 
+  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={(error) => {
-        const result = state.onError(error, state); // TODO: onError is not refreshed
-        if (result instanceof Redirection) {
-          return "Redirection inside ErrorBoundary is not allowed.";
-        }
-        return result as ReactNode;
-      }}
-    >
+    <ErrorBoundary fallback={fallback}>
       {element}
     </ErrorBoundary>
   );

package/src/core/contexts/AlephaProvider.tsx

@@ -0,0 +1,41 @@
+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>
+  );
+};

package/src/core/contexts/RouterLayerContext.ts

@@ -1,8 +1,10 @@
 import { createContext } from "react";
+import type { ErrorHandler } from "../primitives/$page.ts";
 
 export interface RouterLayerContextValue {
   index: number;
   path: string;
+  onError: ErrorHandler;
 }
 
 export const RouterLayerContext = createContext<

package/src/core/hooks/useAction.ts

@@ -13,6 +13,7 @@ import {
 } from "react";
 import { useAlepha } from "./useAlepha.ts";
 import { useInject } from "./useInject.ts";
+import type { Async } from "alepha";
 
 /**
  * Hook for handling async actions with automatic error handling and event emission.
@@ -361,7 +362,7 @@ export interface UseActionOptions<Args extends any[] = any[], Result = any> {
    * The async action handler function.
    * Receives the action arguments plus an ActionContext as the last parameter.
    */
-  handler: (...args: [...Args, ActionContext]) => Promise<Result>;
+  handler: (...args: [...Args, ActionContext]) => Async<Result>;
 
   /**
    * Custom error handler. If provided, prevents default error re-throw.
@@ -378,6 +379,8 @@ export interface UseActionOptions<Args extends any[] = any[], Result = any> {
    */
   id?: string;
 
+  name?: string;
+
   /**
    * Debounce delay in milliseconds. If specified, the action will only execute
    * after the specified delay has passed since the last call. Useful for search inputs

package/src/core/index.shared.ts

@@ -1,3 +1,4 @@
+export * from "./contexts/AlephaProvider.tsx";
 export * from "./contexts/AlephaContext.ts";
 export * from "./hooks/useAction.ts";
 export * from "./hooks/useAlepha.ts";