@tpzdsp/next-toolkit 1.2.9 → 1.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tpzdsp/next-toolkit",
-  "version": "1.2.9",
+  "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",
@@ -111,6 +116,7 @@
     "@storybook/react": "8.6.14",
     "@storybook/react-vite": "8.6.14",
     "@storybook/test": "^8.6.14",
+    "@storybook/types": "8.6.14",
     "@tailwindcss/typography": "^0.5.16",
     "@testing-library/dom": "^10.4.0",
     "@testing-library/jest-dom": "^6.6.3",
@@ -129,6 +135,8 @@
     "@vitest/coverage-v8": "^3.2.4",
     "@vitest/eslint-plugin": "^1.3.4",
     "autoprefixer": "^10.4.21",
+    "buffer": "^6.0.3",
+    "crypto-browserify": "^3.12.1",
     "eslint": "^9.30.1",
     "eslint-config-prettier": "^10.1.8",
     "eslint-import-resolver-alias": "^1.1.2",
@@ -155,19 +163,23 @@
     "prettier": "^3.6.2",
     "prettier-plugin-classnames": "^0.8.1",
     "prettier-plugin-tailwindcss": "^0.6.14",
+    "process": "^0.11.10",
     "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",
     "rollup-plugin-peer-deps-external": "^2.2.4",
     "semantic-release": "^24.2.7",
     "storybook": "8.6.14",
+    "stream-browserify": "^3.0.0",
     "tailwind-merge": "^3.3.1",
     "tailwindcss": "^3.4.16",
     "typescript": "~5.8.3",
     "typescript-eslint": "^8.35.1",
+    "util": "^0.12.5",
     "vite": "^7.0.4",
     "vite-plugin-dts": "^4.5.4",
     "vitest": "^3.2.4"
@@ -187,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/Card/Card.stories.tsx

@@ -1,7 +1,10 @@
+import { FaChevronRight } from 'react-icons/fa6';
+
 /* eslint-disable storybook/no-renderer-packages */
 import type { Meta, StoryFn } from '@storybook/react';
 
 import { Card, type CardProps } from './Card';
+import { Paragraph } from '../Paragraph/Paragraph';
 
 export default {
   children: 'Card',
@@ -33,3 +36,21 @@ ImageAndText.args = {
     </div>
   ),
 };
+
+export const WithLink = Template.bind({});
+WithLink.args = {
+  children: (
+    <>
+      <a
+        href="https://google.co.uk"
+        className="mb-4 flex flex-nowrap items-center gap-2 justify-between font-bold"
+      >
+        <strong>title</strong>
+
+        <FaChevronRight className="text-base" />
+      </a>
+
+      <Paragraph>Some descriptive text</Paragraph>
+    </>
+  ),
+};

package/src/components/Card/Card.test.tsx

@@ -1,12 +1,51 @@
-import { describe, expect, it } from 'vitest';
-
 import { Card } from './Card';
-import { render, screen } from '../../test/renderers';
+import { render, screen, userEvent, within } from '../../test/renderers';
+
+describe('Card Component', () => {
+  it('renders children correctly', () => {
+    render(
+      <Card>
+        <p>Hello, World!</p>
+      </Card>,
+    );
+
+    expect(within(screen.getByRole('article')).getByText('Hello, World!')).toBeInTheDocument();
+  });
+
+  it('renders a link inside the card and handles click', async () => {
+    const user = userEvent.setup();
+    const handleClick = vi.fn();
+
+    render(
+      <Card>
+        <a href="/some-path" onClick={handleClick}>
+          Go to page
+        </a>
+      </Card>,
+    );
+
+    const link = screen.getByRole('link', { name: /go to page/i });
+
+    expect(link).toBeInTheDocument();
+
+    await user.click(link);
+    expect(handleClick).toHaveBeenCalled();
+  });
+
+  it('merges custom className correctly', () => {
+    render(<Card className="bg-red-500 rounded-lg">Custom</Card>);
+    const article = screen.getByRole('article');
+
+    expect(article).toHaveClass('bg-red-500');
+    expect(article).toHaveClass('rounded-lg');
+  });
 
-describe('Card', () => {
-  it('renders with default color blue', () => {
-    render(<Card>Some test text</Card>);
+  it('overrides conflicting className using twMerge', () => {
+    render(<Card className="pt-4">Override Padding</Card>);
+    const article = screen.getByRole('article');
 
-    expect(screen.getByRole('article')).toBeInTheDocument();
+    // Should NOT have original 'pt-[12px]' due to twMerge override
+    expect(article?.className).not.toMatch(/pt-\[12px\]/);
+    expect(article).toHaveClass('pt-4');
   });
 });

package/src/components/Card/Card.tsx

@@ -9,7 +9,7 @@ export const Card = ({ className, children }: CardProps) => {
   return (
     <article
       className={twMerge(
-        'relative my-6 flex w-96 flex-col rounded-lg border border-slate-200 bg-white p-2 shadow-sm',
+        'h-full flex flex-col pt-[12px] px-[4px] mx-3 border-t border-slate-500',
         className,
       )}
     >

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/Paragraph/Paragraph.tsx

@@ -1,7 +1,11 @@
-export type ParagraphProps = {
-  children: React.ReactNode;
-};
+import type { ExtendProps } from '../../types/utils';
+
+export type ParagraphProps = ExtendProps<'p'>;
 
-export const Paragraph = ({ children }: ParagraphProps) => {
-  return <p className="pb-4 text-sm text-text-primary">{children}</p>;
+export const Paragraph = ({ className, children, ...props }: ParagraphProps) => {
+  return (
+    <p className={`pb-4 text-sm text-text-primary ${className}`} {...props}>
+      {children}
+    </p>
+  );
 };