@ereo/client 0.1.6

package/README.md

@@ -0,0 +1,93 @@
+# @ereo/client
+
+Client-side runtime for the EreoJS framework. Includes islands architecture, client-side navigation, prefetching, forms, and error boundaries.
+
+## Installation
+
+```bash
+bun add @ereo/client
+```
+
+## Quick Start
+
+```typescript
+import { initClient, Link, useLoaderData } from '@ereo/client';
+
+// Initialize the client runtime
+initClient();
+
+// Use loader data in components
+function UserProfile() {
+  const { user } = useLoaderData<{ user: { name: string } }>();
+  return <h1>{user.name}</h1>;
+}
+
+// Client-side navigation with prefetching
+function Nav() {
+  return <Link to="/dashboard" prefetch="intent">Dashboard</Link>;
+}
+```
+
+## Key Features
+
+- **Islands Architecture** - Partial hydration with `createIsland` and `hydrateIslands`
+- **Client Navigation** - SPA-like navigation with `navigate`, `goBack`, `goForward`
+- **Prefetching** - Smart prefetching with `prefetch`, hover and viewport strategies
+- **Data Hooks** - `useLoaderData`, `useActionData`, `useNavigation`, `useError`
+- **Link Components** - `Link` and `NavLink` with active state detection
+- **Forms** - Enhanced forms with `Form`, `useSubmit`, `useFetcher`
+- **Error Boundaries** - Graceful error handling with `ErrorBoundary` and `RouteErrorBoundary`
+- **Scroll Restoration** - Automatic scroll position management
+
+## Forms Example
+
+```tsx
+import { Form, useSubmit, useNavigation } from '@ereo/client';
+
+function ContactForm() {
+  const submit = useSubmit();
+  const navigation = useNavigation();
+  const isSubmitting = navigation.state === 'submitting';
+
+  return (
+    <Form method="post" action="/contact">
+      <input name="email" type="email" required />
+      <button disabled={isSubmitting}>
+        {isSubmitting ? 'Sending...' : 'Send'}
+      </button>
+    </Form>
+  );
+}
+```
+
+## Islands
+
+```tsx
+import { createIsland } from '@ereo/client';
+import Chart from './Chart';
+
+// Create an island wrapper for selective hydration
+const InteractiveChart = createIsland(Chart, 'Chart');
+
+// Use with hydration directives
+function Page() {
+  return (
+    <div>
+      <h1>Dashboard</h1>
+      <InteractiveChart client:visible data={chartData} />
+    </div>
+  );
+}
+```
+
+## Documentation
+
+For full documentation, visit [https://ereojs.dev/docs/client](https://ereojs.dev/docs/client)
+
+## Part of EreoJS
+
+This package is part of the [EreoJS](https://github.com/ereojs/ereo) monorepo - a modern full-stack framework built for Bun.
+
+## License
+
+MIT

package/dist/error-boundary.d.ts

@@ -0,0 +1,215 @@
+/**
+ * @ereo/client - Error Boundary Context and Recovery System
+ *
+ * Provides error boundaries, context, and recovery utilities for the EreoJS framework.
+ */
+import { Component, type ReactNode, type ErrorInfo, type ComponentType } from 'react';
+import type { RouteParams, ErrorConfig } from '@ereo/core';
+import { ErrorContext, type ErrorContextValue } from './hooks';
+/**
+ * Props for the ErrorBoundary component.
+ */
+export interface ErrorBoundaryProps {
+    /** Fallback UI when error occurs */
+    fallback?: ReactNode | ((error: Error, reset: () => void) => ReactNode);
+    /** Called when error is caught */
+    onError?: (error: Error, errorInfo: ErrorInfo) => void;
+    /** Children to render */
+    children: ReactNode;
+}
+/**
+ * State for the ErrorBoundary component.
+ */
+interface ErrorBoundaryState {
+    error: Error | null;
+    errorInfo: ErrorInfo | null;
+}
+/**
+ * Route error response structure.
+ */
+export interface RouteErrorResponse {
+    status: number;
+    statusText: string;
+    data: unknown;
+    internal?: boolean;
+}
+/**
+ * Props for RouteErrorBoundary component.
+ */
+export interface RouteErrorBoundaryProps {
+    /** Route identifier */
+    routeId: string;
+    /** Error configuration from route */
+    errorConfig?: ErrorConfig;
+    /** Children to render */
+    children: ReactNode;
+    /** Fallback component from route module */
+    fallbackComponent?: ComponentType<{
+        error: Error;
+        params: RouteParams;
+    }>;
+    /** Route params */
+    params?: RouteParams;
+}
+/**
+ * Return type for useErrorBoundary hook.
+ */
+export interface UseErrorBoundaryReturn {
+    error: Error | undefined;
+    reset: () => void;
+    showBoundary: (error: Error) => void;
+}
+export { ErrorContext, type ErrorContextValue };
+/**
+ * Error boundary component that catches JavaScript errors in child components.
+ */
+export declare class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundaryState> {
+    constructor(props: ErrorBoundaryProps);
+    /**
+     * Update state when an error is caught.
+     */
+    static getDerivedStateFromError(error: Error): Partial<ErrorBoundaryState>;
+    /**
+     * Log error information and call onError callback.
+     */
+    componentDidCatch(error: Error, errorInfo: ErrorInfo): void;
+    /**
+     * Reset the error state.
+     */
+    reset: () => void;
+    render(): ReactNode;
+}
+/**
+ * Hook to access error boundary functionality.
+ * Provides error state, reset function, and ability to programmatically trigger errors.
+ *
+ * @returns Object with error state and control functions
+ * @throws Error if used outside EreoProvider or ErrorProvider
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { error, reset, showBoundary } = useErrorBoundary();
+ *
+ *   const handleAsyncError = async () => {
+ *     try {
+ *       await fetchData();
+ *     } catch (e) {
+ *       showBoundary(e as Error);
+ *     }
+ *   };
+ *
+ *   return <button onClick={handleAsyncError}>Fetch</button>;
+ * }
+ * ```
+ */
+export declare function useErrorBoundary(): UseErrorBoundaryReturn;
+/**
+ * Hook to get the current route error.
+ * This is a simple implementation that accesses the error from context.
+ *
+ * @returns The current error or undefined
+ *
+ * @example
+ * ```tsx
+ * function ErrorPage() {
+ *   const error = useRouteError();
+ *
+ *   if (isRouteErrorResponse(error)) {
+ *     return <div>HTTP Error: {error.status}</div>;
+ *   }
+ *
+ *   return <div>Unknown error occurred</div>;
+ * }
+ * ```
+ */
+export declare function useRouteError(): unknown;
+/**
+ * Error boundary specifically for route-level error handling.
+ * Integrates with route configuration and supports error recovery strategies.
+ */
+export declare class RouteErrorBoundary extends Component<RouteErrorBoundaryProps, ErrorBoundaryState & {
+    retryCount: number;
+}> {
+    constructor(props: RouteErrorBoundaryProps);
+    static getDerivedStateFromError(error: Error): Partial<ErrorBoundaryState>;
+    componentDidCatch(error: Error, errorInfo: ErrorInfo): void;
+    /**
+     * Reset the error state and optionally retry.
+     */
+    reset: () => void;
+    render(): ReactNode;
+}
+/**
+ * Type guard to check if an error is a RouteErrorResponse.
+ *
+ * @param error - The error to check
+ * @returns True if the error is a RouteErrorResponse
+ *
+ * @example
+ * ```tsx
+ * const error = useRouteError();
+ *
+ * if (isRouteErrorResponse(error)) {
+ *   console.log(error.status); // e.g., 404
+ *   console.log(error.statusText); // e.g., "Not Found"
+ * }
+ * ```
+ */
+export declare function isRouteErrorResponse(error: unknown): error is RouteErrorResponse;
+/**
+ * Create a RouteErrorResponse.
+ *
+ * @param status - HTTP status code
+ * @param statusText - HTTP status text
+ * @param data - Additional error data
+ * @returns A RouteErrorResponse object
+ *
+ * @example
+ * ```tsx
+ * throw createRouteErrorResponse(404, 'Not Found', { message: 'Page not found' });
+ * ```
+ */
+export declare function createRouteErrorResponse(status: number, statusText: string, data?: unknown): RouteErrorResponse;
+/**
+ * Wrap a component with an error boundary.
+ *
+ * @param WrappedComponent - The component to wrap
+ * @param errorBoundaryProps - Props to pass to the error boundary
+ * @returns A new component wrapped with an error boundary
+ *
+ * @example
+ * ```tsx
+ * const SafeComponent = withErrorBoundary(MyComponent, {
+ *   fallback: <div>Something went wrong</div>,
+ *   onError: (error) => console.error(error),
+ * });
+ * ```
+ */
+export declare function withErrorBoundary<P extends object>(WrappedComponent: ComponentType<P>, errorBoundaryProps?: Omit<ErrorBoundaryProps, 'children'>): ComponentType<P>;
+/**
+ * Create a custom error for route responses.
+ *
+ * @example
+ * ```tsx
+ * // In a loader function
+ * export async function loader({ params }: LoaderArgs) {
+ *   const post = await getPost(params.id);
+ *   if (!post) {
+ *     throw new RouteError(404, 'Not Found', { message: 'Post not found' });
+ *   }
+ *   return { post };
+ * }
+ * ```
+ */
+export declare class RouteError extends Error {
+    status: number;
+    statusText: string;
+    data: unknown;
+    constructor(status: number, statusText: string, data?: unknown);
+    /**
+     * Convert to RouteErrorResponse.
+     */
+    toResponse(): RouteErrorResponse;
+}
+//# sourceMappingURL=error-boundary.d.ts.map

package/dist/error-boundary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-boundary.d.ts","sourceRoot":"","sources":["../src/error-boundary.tsx"],"names":[],"mappings":"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"}