@tpzdsp/next-toolkit 1.3.0 → 1.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tpzdsp/next-toolkit",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "A reusable React component library for Next.js applications",
   "type": "module",
   "private": false,
@@ -53,6 +53,11 @@
       "import": "./src/map/index.ts",
       "require": "./src/map/index.ts"
     },
+    "./errors": {
+      "types": "./src/errors/index.ts",
+      "import": "./src/errors/index.ts",
+      "require": "./src/errors/index.ts"
+    },
     "./types": {
       "types": "./src/types/index.ts",
       "import": "./src/types/index.ts",
@@ -162,6 +167,7 @@
     "proj4": "^2.19.10",
     "react": "^19.1.0",
     "react-dom": "^19.1.0",
+    "react-error-boundary": "^6.0.0",
     "react-icons": "^5.5.0",
     "react-select": "^5.10.2",
     "react-select-event": "^5.5.1",
@@ -193,6 +199,7 @@
     "proj4": "^2.19.10",
     "react": "^19.1.0",
     "react-dom": "^19.1.0",
+    "react-error-boundary": "^6.0.0",
     "react-icons": "^5.5.0"
   },
   "peerDependenciesMeta": {

package/src/components/ErrorBoundary/ErrorBoundary.stories.tsx

@@ -0,0 +1,89 @@
+/* eslint-disable storybook/no-renderer-packages */
+import type { FallbackProps } from 'react-error-boundary';
+
+import type { Meta, StoryObj } from '@storybook/react';
+
+import { ErrorBoundary } from './ErrorBoundary';
+
+// Component that intentionally throws an error
+const Bomb = () => {
+  throw new Error('Boom!');
+};
+
+// Simple custom fallback for demonstration
+const CustomFallback = ({ error, resetErrorBoundary }: FallbackProps) => (
+  <div role="alert" className="p-4 border border-red-300 rounded-lg bg-red-50">
+    <p className="font-medium text-red-700">Custom Fallback:</p>
+
+    <p className="text-red-600">{error.message}</p>
+
+    <button
+      className="px-3 py-1 mt-2 text-white bg-red-600 rounded hover:bg-red-700"
+      onClick={resetErrorBoundary}
+    >
+      Try Again
+    </button>
+  </div>
+);
+
+const meta = {
+  title: 'Components/ErrorBoundary',
+  component: ErrorBoundary,
+  parameters: {
+    layout: 'centered',
+    docs: {
+      description: {
+        component:
+          'A wrapper around `react-error-boundary` that catches errors in the component tree and renders a fallback UI.',
+      },
+    },
+  },
+  tags: ['autodocs'],
+} satisfies Meta<typeof ErrorBoundary>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: {
+    children: (
+      <div className="p-4 text-green-800 border rounded-md bg-green-50">
+        <p>No errors here — everything renders normally.</p>
+      </div>
+    ),
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Default behavior — children render normally when no error is thrown.',
+      },
+    },
+  },
+};
+
+export const WithError: Story = {
+  args: {
+    children: <Bomb />,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'When a child throws an error, the default fallback UI is displayed.',
+      },
+    },
+  },
+};
+
+export const WithCustomFallback: Story = {
+  args: {
+    children: <Bomb />,
+    fallback: CustomFallback,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'ErrorBoundary can render a custom fallback component when errors occur.',
+      },
+    },
+  },
+};

package/src/components/ErrorBoundary/ErrorBoundary.test.tsx

@@ -0,0 +1,75 @@
+import type { FallbackProps } from 'react-error-boundary';
+
+import { ErrorBoundary } from './ErrorBoundary';
+import { render, screen, userEvent } from '../../test/renderers';
+import { identityFn } from '../../utils/utils';
+
+// Component that always throws
+const Bomb = () => {
+  throw new Error('Boom!');
+};
+
+// Custom fallback with button for reset
+const CustomFallback = ({ error, resetErrorBoundary }: FallbackProps) => (
+  <div role="alert">
+    <p>Custom fallback: {error.message}</p>
+
+    <button onClick={resetErrorBoundary}>Try again</button>
+  </div>
+);
+
+describe('ErrorBoundary', () => {
+  it('renders children when no error is thrown', () => {
+    render(
+      <ErrorBoundary>
+        <p>Safe content</p>
+      </ErrorBoundary>,
+    );
+
+    expect(screen.getByRole('paragraph')).toHaveTextContent('Safe content');
+  });
+
+  it('renders default ErrorFallback when an error is thrown', () => {
+    render(
+      <ErrorBoundary>
+        <Bomb />
+      </ErrorBoundary>,
+    );
+
+    expect(screen.getByRole('alert')).toBeInTheDocument();
+  });
+
+  it('calls console.error when an error is thrown', () => {
+    const consoleSpy = vi.spyOn(console, 'error').mockImplementation(identityFn);
+
+    render(
+      <ErrorBoundary>
+        <Bomb />
+      </ErrorBoundary>,
+    );
+
+    expect(screen.getByRole('alert')).toBeInTheDocument();
+    expect(consoleSpy).toHaveBeenCalled();
+
+    consoleSpy.mockRestore();
+  });
+
+  it('supports a custom fallback component with reset', async () => {
+    const user = userEvent.setup();
+
+    render(
+      <ErrorBoundary fallback={CustomFallback}>
+        <Bomb />
+      </ErrorBoundary>,
+    );
+
+    const alert = screen.getByRole('alert');
+
+    expect(alert).toHaveTextContent('Custom fallback: Boom!');
+
+    await user.click(screen.getByRole('button', { name: /try again/i }));
+
+    // Child will throw again immediately, so fallback remains
+    expect(screen.getByRole('alert')).toBeInTheDocument();
+  });
+});

package/src/components/ErrorBoundary/ErrorBoundary.tsx

@@ -0,0 +1,28 @@
+import type { ComponentType, ErrorInfo, ReactNode } from 'react';
+
+import { ErrorBoundary as ReactErrorBoundary, type FallbackProps } from 'react-error-boundary';
+
+import { ErrorFallback } from './ErrorFallback';
+
+type ErrorBoundaryProps = {
+  children: ReactNode;
+  fallback?: ComponentType<FallbackProps>;
+  onReset?: () => void;
+};
+
+export const ErrorBoundary = ({ children, fallback, onReset }: ErrorBoundaryProps) => {
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  const logError = (error: Error, info: ErrorInfo) => {
+    // send error to third party api, etc
+  };
+
+  return (
+    <ReactErrorBoundary
+      FallbackComponent={fallback ?? ErrorFallback}
+      onError={logError}
+      onReset={onReset}
+    >
+      {children}
+    </ReactErrorBoundary>
+  );
+};

package/src/components/ErrorBoundary/ErrorFallback.stories.tsx

@@ -0,0 +1,70 @@
+/* eslint-disable storybook/no-renderer-packages */
+import type { Meta, StoryObj } from '@storybook/react';
+
+import { ErrorFallback } from './ErrorFallback';
+import { ApiError } from '../../errors/ApiError';
+import { Http } from '../../utils/http';
+
+const meta = {
+  title: 'Components/ErrorFallback',
+  component: ErrorFallback,
+  parameters: {
+    layout: 'centered',
+    docs: {
+      description: {
+        component:
+          'A UI component displayed when an error is caught by `ErrorBoundary`. It shows the error message, optional cause, and a retry button.',
+      },
+    },
+  },
+  tags: ['autodocs'],
+} satisfies Meta<typeof ErrorFallback>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// Shared mock reset fn
+const mockReset = () => alert('Reset error boundary called');
+
+export const Default: Story = {
+  args: {
+    error: new Error('Something went wrong'),
+    resetErrorBoundary: mockReset,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Default rendering when given a standard JavaScript `Error`.',
+      },
+    },
+  },
+};
+
+export const WithApiError: Story = {
+  args: {
+    error: new ApiError('Request failed', Http.InternalServerError, undefined, 'Extra details'),
+    resetErrorBoundary: mockReset,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Rendering when the error is an `ApiError` that includes extra details.',
+      },
+    },
+  },
+};
+
+export const WithUnknownError: Story = {
+  args: {
+    error: {} as unknown as Error,
+    resetErrorBoundary: mockReset,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'If the error is not an `Error` or `ApiError`, a generic "Unknown" message is shown.',
+      },
+    },
+  },
+};

package/src/components/ErrorBoundary/ErrorFallback.test.tsx

@@ -0,0 +1,54 @@
+import { ErrorFallback } from './ErrorFallback';
+import { ApiError } from '../../errors';
+import { render, screen, userEvent } from '../../test/renderers';
+import { Http } from '../../utils/http';
+import { identityFn } from '../../utils/utils';
+
+describe('ErrorFallback', () => {
+  it('renders a generic error message for an unknown error type', () => {
+    render(<ErrorFallback error={{} as unknown as Error} resetErrorBoundary={identityFn} />);
+
+    const alert = screen.getByRole('alert');
+
+    expect(alert).toHaveTextContent(/there was an error/i);
+    expect(alert).toHaveTextContent(/reason: unknown/i);
+  });
+
+  it('renders message for standard Error instance', () => {
+    const error = new Error('Something went wrong');
+
+    render(<ErrorFallback error={error} resetErrorBoundary={identityFn} />);
+
+    expect(screen.getByText(/reason: something went wrong/i)).toBeInTheDocument();
+  });
+
+  it('renders message and cause for ApiError instance', () => {
+    const apiError = new ApiError('Fake Reason', Http.InternalServerError);
+
+    render(<ErrorFallback error={apiError} resetErrorBoundary={identityFn} />);
+
+    expect(screen.getByText(/reason: fake reason/i)).toBeInTheDocument();
+  });
+
+  it('renders cause only when it is a string', () => {
+    const error = new Error('Has a cause', { cause: ["I won't display"] });
+
+    render(<ErrorFallback error={error} resetErrorBoundary={identityFn} />);
+
+    expect(screen.getByText(/reason: has a cause/i)).toBeInTheDocument();
+    expect(screen.queryByText(/cause:/i)).not.toBeInTheDocument();
+  });
+
+  it('calls resetErrorBoundary when Try Again is clicked', async () => {
+    const user = userEvent.setup();
+    const resetSpy = vi.fn();
+
+    render(<ErrorFallback error={new Error('Test error')} resetErrorBoundary={resetSpy} />);
+
+    const button = screen.getByRole('button', { name: /try again/i });
+
+    await user.click(button);
+
+    expect(resetSpy).toHaveBeenCalledTimes(1);
+  });
+});

package/src/components/ErrorBoundary/ErrorFallback.tsx

@@ -0,0 +1,30 @@
+import { type FallbackProps } from 'react-error-boundary';
+
+import { Button, ErrorText } from '@tpzdsp/next-toolkit/components';
+
+import { ApiError } from '../../errors/ApiError';
+
+export const ErrorFallback = ({ resetErrorBoundary, error }: FallbackProps) => {
+  let message;
+  let cause = undefined;
+
+  if (error instanceof ApiError) {
+    message = error.message;
+    cause = error.details;
+  } else if (error instanceof Error) {
+    ({ message, cause } = error);
+  } else {
+    message = 'Unknown';
+  }
+
+  return (
+    <div>
+      <ErrorText>
+        <p>There was an error. (Reason: {message})</p>
+        {typeof cause === 'string' ? <p>Cause: {cause}</p> : null}
+      </ErrorText>
+
+      <Button onClick={resetErrorBoundary}>Try Again</Button>
+    </div>
+  );
+};

package/src/components/index.ts

@@ -44,6 +44,8 @@ export { useDropdownMenu } from './dropdown/useDropdownMenu';
 export { SlidingPanel } from './SlidingPanel/SlidingPanel';
 export { Accordion } from './accordion/Accordion';
 export { Modal } from './Modal/Modal';
+export { ErrorBoundary } from './ErrorBoundary/ErrorBoundary';
+export { ErrorFallback } from './ErrorBoundary/ErrorFallback';
 // NOTE: Select components moved to separate entry point '@tpzdsp/next-toolkit/components/select'
 // export { Select } from './select/Select';
 // export { SelectSkeleton } from './select/SelectSkeleton';

package/src/errors/ApiError.ts

@@ -0,0 +1,71 @@
+/* eslint-disable no-restricted-syntax */
+
+import { Http } from '../utils/http';
+
+export class ApiError extends Error {
+  public readonly status: number;
+  public readonly code?: string;
+  public readonly details?: unknown;
+
+  constructor(message: string, status: number, code?: string, details?: unknown) {
+    super(message);
+    this.name = 'ApiError';
+    this.status = status;
+    this.code = code;
+    this.details = details;
+
+    // Maintains proper stack trace for where our error was thrown (only available on V8)
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, ApiError);
+    }
+  }
+
+  // Helper method to check if it's a client error (4xx)
+  get isClientError(): boolean {
+    return this.status >= Http.BadRequest && this.status < Http.InternalServerError;
+  }
+
+  // Helper method to check if it's a server error (5xx)
+  get isServerError(): boolean {
+    return this.status >= Http.InternalServerError;
+  }
+
+  // Convert to a plain object for JSON serialization
+  toJSON() {
+    return {
+      name: this.name,
+      message: this.message,
+      status: this.status,
+      code: this.code,
+      details: this.details,
+    };
+  }
+
+  // Static factory methods for common error types
+  static badRequest(message: string, details?: unknown): ApiError {
+    return new ApiError(message, Http.BadRequest, 'BAD_REQUEST', details);
+  }
+
+  static notFound(message = 'Resource not found'): ApiError {
+    return new ApiError(message, Http.NotFound, 'NOT_FOUND');
+  }
+
+  static unauthorized(message = 'Unauthorized'): ApiError {
+    return new ApiError(message, Http.Unauthorized, 'UNAUTHORIZED');
+  }
+
+  static forbidden(message = 'Forbidden'): ApiError {
+    return new ApiError(message, Http.Forbidden, 'FORBIDDEN');
+  }
+
+  static internalServerError(message = 'Internal server error'): ApiError {
+    return new ApiError(message, Http.InternalServerError, 'INTERNAL_SERVER_ERROR');
+  }
+
+  static fromResponse(response: Response, message?: string): ApiError {
+    return new ApiError(
+      message ?? `HTTP ${response.status}: ${response.statusText}`,
+      response.status,
+    );
+  }
+}

package/src/errors/index.ts

@@ -0,0 +1 @@
+export * from './ApiError';

package/src/utils/utils.ts

@@ -65,3 +65,6 @@ export const formatBytes = (bytes: number, decimals = 2): string => {
 
   return parseFloat((bytes / Math.pow(k, i)).toFixed(dm)) + ' ' + sizes[i];
 };
+
+// eslint-disable-next-line  @typescript-eslint/no-empty-function
+export const identityFn = () => {};