@tpzdsp/next-toolkit 1.7.0 → 1.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tpzdsp/next-toolkit",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "description": "A reusable React component library for Next.js applications",
   "type": "module",
   "private": false,
@@ -150,6 +150,7 @@
     "autoprefixer": "^10.4.21",
     "buffer": "^6.0.3",
     "crypto-browserify": "^3.12.1",
+    "date-fns": "^4.1.0",
     "eslint": "^9.30.1",
     "eslint-config-prettier": "^10.1.8",
     "eslint-import-resolver-alias": "^1.1.2",
@@ -206,6 +207,7 @@
     "@turf/turf": "^7.2.0",
     "@types/geojson": "^7946.0.16",
     "@types/jsonwebtoken": "^9.0.10",
+    "date-fns": "^4.1.0",
     "geojson": "^0.5.0",
     "jsonwebtoken": "^9.0.2",
     "next": "^15.4.2",
@@ -220,6 +222,12 @@
     "zod": "^4.1.8"
   },
   "peerDependenciesMeta": {
+    "@tanstack/react-query": {
+      "optional": true
+    },
+    "@better-fetch/fetch": {
+      "optional": true
+    },
     "@turf/turf": {
       "optional": true
     },
@@ -229,6 +237,9 @@
     "@types/jsonwebtoken": {
       "optional": true
     },
+    "date-fns": {
+      "optional": true
+    },
     "geojson": {
       "optional": true
     },
@@ -249,6 +260,9 @@
     },
     "react-select": {
       "optional": true
+    },
+    "zod": {
+      "optional": true
     }
   },
   "optionalDependencies": {

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

@@ -13,7 +13,7 @@ const meta = {
     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.',
+          'Displayed when an error is caught by `ErrorBoundary`. Shows the error message, optional details in an Accordion, and Copy/Retry buttons.',
       },
     },
   },
@@ -23,7 +23,7 @@ const meta = {
 export default meta;
 type Story = StoryObj<typeof meta>;
 
-// Shared mock reset fn
+// Shared mock reset function
 const mockReset = () => alert('Reset error boundary called');
 
 export const Default: Story = {
@@ -34,7 +34,8 @@ export const Default: Story = {
   parameters: {
     docs: {
       description: {
-        story: 'Default rendering when given a standard JavaScript `Error`.',
+        story:
+          'Default rendering with a standard JavaScript `Error`. Shows heading, reason, and Copy/Retry buttons.',
       },
     },
   },
@@ -42,13 +43,14 @@ export const Default: Story = {
 
 export const WithApiError: Story = {
   args: {
-    error: new ApiError('Request failed', HttpStatus.InternalServerError, 'Extra details'),
+    error: new ApiError('Request failed', HttpStatus.InternalServerError, 'Some technical details'),
     resetErrorBoundary: mockReset,
   },
   parameters: {
     docs: {
       description: {
-        story: 'Rendering when the error is an `ApiError` that includes extra details.',
+        story:
+          'Rendering when the error is an `ApiError`. Shows reason, details in an Accordion, digest, and Copy/Retry buttons.',
       },
     },
   },
@@ -63,7 +65,7 @@ export const WithUnknownError: Story = {
     docs: {
       description: {
         story:
-          'If the error is not an `Error` or `ApiError`, a generic "Unknown" message is shown.',
+          'If the error is not an `Error` or `ApiError`, a generic "Unknown error" message is shown, with Copy/Retry buttons.',
       },
     },
   },

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

@@ -1,54 +1,107 @@
 import { ErrorFallback } from './ErrorFallback';
 import { ApiError } from '../../errors';
 import { HttpStatus } from '../../http';
-import { render, screen, userEvent } from '../../test/renderers';
+import { render, screen, userEvent, within } from '../../test/renderers';
 import { identityFn } from '../../utils/utils';
 
+const FAKE_UUID = 'fake-uuid';
+
+Object.defineProperty(navigator, 'clipboard', {
+  value: {
+    writeText: vi.fn().mockResolvedValue(undefined),
+  },
+  configurable: true,
+});
+
 describe('ErrorFallback', () => {
+  beforeEach(() => {
+    (navigator.clipboard.writeText as unknown) = vi.fn().mockResolvedValue(undefined);
+    vi.spyOn(crypto, 'randomUUID').mockReturnValue(FAKE_UUID);
+  });
+
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
   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(/something went wrong/i);
     expect(alert).toHaveTextContent(/reason: unknown/i);
   });
 
   it('renders message for standard Error instance', () => {
-    const error = new Error('Something went wrong');
+    const error = new Error('custom error message');
 
     render(<ErrorFallback error={error} resetErrorBoundary={identityFn} />);
 
-    expect(screen.getByText(/reason: something went wrong/i)).toBeInTheDocument();
+    expect(screen.getByRole('alert')).toHaveTextContent(/reason: custom error message/i);
   });
 
-  it('renders message and cause for ApiError instance', () => {
-    const apiError = new ApiError('Fake Reason', HttpStatus.InternalServerError);
+  it('renders message, details and digest for ApiError instance', async () => {
+    const apiError = new ApiError('Fake Reason', HttpStatus.InternalServerError, 'Some details');
 
     render(<ErrorFallback error={apiError} resetErrorBoundary={identityFn} />);
 
-    expect(screen.getByText(/reason: fake reason/i)).toBeInTheDocument();
+    // Message shown
+    expect(screen.getByRole('alert')).toHaveTextContent(/reason: fake reason/i);
+
+    // Accordion exists but details hidden until toggled
+    const accordionButton = screen.getByRole('button', { name: /show details/i });
+
+    expect(accordionButton).toBeInTheDocument();
+
+    // Expand and check details text
+    await userEvent.click(accordionButton);
+
+    const section = screen.getByRole('region', { hidden: false });
+
+    expect(within(section).getByText(/error id:/i)).toBeInTheDocument();
+    expect(within(section).getByText(/some details/i)).toBeInTheDocument();
   });
 
-  it('renders cause only when it is a string', () => {
-    const error = new Error('Has a cause', { cause: ["I won't display"] });
+  it('renders non-string causes', () => {
+    const error = new Error('Has a cause', { cause: ['I will display'] });
 
     render(<ErrorFallback error={error} resetErrorBoundary={identityFn} />);
 
-    expect(screen.getByText(/reason: has a cause/i)).toBeInTheDocument();
-    expect(screen.queryByText(/cause:/i)).not.toBeInTheDocument();
+    expect(screen.getByRole('alert')).toHaveTextContent(/reason: has a cause/i);
+    expect(screen.queryByRole('button', { name: /show details/i })).toBeInTheDocument();
   });
 
-  it('calls resetErrorBoundary when Try Again is clicked', async () => {
+  it('calls resetErrorBoundary when Retry 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 });
+    const button = screen.getByRole('button', { name: /retry/i });
 
     await user.click(button);
 
     expect(resetSpy).toHaveBeenCalledTimes(1);
   });
+
+  it('copies error info to clipboard when Copy is clicked', async () => {
+    const user = userEvent.setup();
+    const apiError = new ApiError('Copy Reason', HttpStatus.BadRequest, 'Some details');
+
+    render(<ErrorFallback error={apiError} resetErrorBoundary={identityFn} />);
+
+    const copyButton = screen.getByRole('button', { name: /copy/i });
+
+    await user.click(copyButton);
+
+    expect(navigator.clipboard.writeText).toHaveBeenCalledWith(
+      expect.stringContaining('App Error: Copy Reason'),
+    );
+    expect(navigator.clipboard.writeText).toHaveBeenCalledWith(
+      expect.stringContaining('Details: Some details'),
+    );
+    expect(navigator.clipboard.writeText).toHaveBeenCalledWith(
+      expect.stringContaining(`Digest: ${FAKE_UUID}`),
+    );
+  });
 });

package/src/components/ErrorBoundary/ErrorFallback.tsx

@@ -1,10 +1,16 @@
-import { type FallbackProps } from 'react-error-boundary';
+import { useId } from 'react';
 
-import { Button, ErrorText } from '@tpzdsp/next-toolkit/components';
+import { type FallbackProps } from 'react-error-boundary';
 
 import { ApiError } from '../../errors/ApiError';
+import { Accordion } from '../accordion/Accordion';
+import { Button } from '../Button/Button';
+import { Heading } from '../Heading/Heading';
+import { Paragraph } from '../Paragraph/Paragraph';
 
 export const ErrorFallback = ({ resetErrorBoundary, error }: FallbackProps) => {
+  const id = useId();
+
   let message;
   let details = undefined;
   let digest = undefined;
@@ -12,35 +18,67 @@ export const ErrorFallback = ({ resetErrorBoundary, error }: FallbackProps) => {
   if (error instanceof ApiError) {
     message = error.message;
     details = error.details;
+    digest = error.digest;
   } else if (error instanceof Error) {
     message = error.message;
     details = error.cause?.toString();
   } else {
-    message = 'Unknown';
+    message = 'Unknown error';
   }
 
+  const copyToClipboard = () => {
+    navigator.clipboard.writeText(
+      // eslint-disable-next-line sonarjs/no-nested-template-literals
+      `App Error: ${message}, ${details ? `Details: ${details}, ` : ''}${digest ? `Digest: ${digest}` : ''}`,
+    );
+  };
+
   return (
-    <div>
-      <ErrorText>
-        There was an error. <br />
-        Reason: {message}
-      </ErrorText>
-      {details ? (
-        <span>
-          <br />
-
-          <details>
-            <summary>Details</summary>
-
-            <pre>{details}</pre>
-          </details>
-        </span>
-      ) : (
-        <></>
+    <div
+      role="alert"
+      aria-labelledby={id}
+      className="grid gap-2 border-form border-transparent border-l-error max-w-full pl-2"
+      style={{ gridTemplateColumns: '1fr auto' }}
+    >
+      <div className="flex flex-col gap-0.5">
+        <Heading id={id} type="h3" className="text-error text-base font-semibold py-0">
+          Something went wrong
+        </Heading>
+
+        <Paragraph className="leading-snug pb-0">
+          <strong>Reason:</strong> {message}
+        </Paragraph>
+      </div>
+
+      <div className="flex items-start gap-1">
+        <Button onClick={copyToClipboard} variant="secondary" className="shrink-0">
+          Copy
+        </Button>
+
+        <Button onClick={resetErrorBoundary} variant="secondary" className="shrink-0">
+          Retry
+        </Button>
+      </div>
+
+      {details && (
+        <div className="col-span-2">
+          <Accordion title="Show details">
+            <div className="flex gap-0.5 flex-col">
+              {digest && (
+                <Paragraph className="leading-snug pb-0">
+                  <strong>Error ID:</strong> {digest}
+                </Paragraph>
+              )}
+              <pre
+                className="text-base bg-white border border-gray-200 p-2 overflow-y-auto max-h-32
+                  whitespace-pre-wrap"
+              >
+                {details}
+              </pre>
+            </div>
+          </Accordion>
+        </div>
       )}
-      <br />
-      Digest: {digest ?? 'No digest provided'}
-      <Button onClick={resetErrorBoundary}>Try Again</Button>
     </div>
   );
 };

package/src/components/ErrorText/ErrorText.tsx

@@ -5,13 +5,15 @@ import type { ExtendProps } from '../../types/utils';
 export type ErrorTextProps = ExtendProps<'p'>;
 
 export const ErrorText = ({ className, children, ...props }: ErrorTextProps) => {
+  const Component = typeof children === 'string' ? 'p' : 'div';
+
   return (
-    <p
+    <Component
       role="alert"
       className={twMerge('mb-3 text-base text-error font-bold', className)}
       {...props}
     >
       {children}
-    </p>
+    </Component>
   );
 };

package/src/components/Heading/Heading.tsx

@@ -1,11 +1,14 @@
 import { twMerge } from 'tailwind-merge';
 
-export type HeadingProps = {
+import type { ExtendProps } from '../../types';
+
+type Props = {
   type: 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6';
-  className?: string;
-  children: React.ReactNode;
 };
 
+// h1 through h6 have identical props
+export type HeadingProps = ExtendProps<'h1', Props>;
+
 export const Heading = ({ type, className, children }: HeadingProps) => {
   switch (type) {
     case 'h1':

package/src/components/Paragraph/Paragraph.tsx

@@ -1,10 +1,12 @@
+import { twMerge } from 'tailwind-merge';
+
 import type { ExtendProps } from '../../types/utils';
 
 export type ParagraphProps = ExtendProps<'p'>;
 
 export const Paragraph = ({ className, children, ...props }: ParagraphProps) => {
   return (
-    <p className={`pb-4 text-sm text-text-primary ${className}`} {...props}>
+    <p className={twMerge('pb-4 text-sm text-text-primary', className)} {...props}>
       {children}
     </p>
   );

package/src/map/MapComponent.tsx

@@ -75,7 +75,7 @@ export const MapComponent = ({
     }
 
     // Initialise map's basemap layers.
-    const layers = initializeBasemapLayers();
+    const layers = initializeBasemapLayers(basePath);
 
     const target = mapRef.current;
 

package/src/map/basemaps.ts

@@ -8,7 +8,7 @@ import SatelliteMapTilerImage from './images/basemaps/satellite-map-tiler.png';
 import SatelliteImage from './images/basemaps/satellite.png';
 import StreetsImage from './images/basemaps/streets.png';
 
-export const initializeBasemapLayers = () => {
+export const initializeBasemapLayers = (baseUrl: string) => {
   const osmLayer = new TileLayer({
     preload: Infinity,
     source: new OSM(),
@@ -24,7 +24,7 @@ export const initializeBasemapLayers = () => {
   const osMapsLight = new TileLayer({
     // attributions: [`© Crown Copyright and Database Rights [insert year of creation] OS AC0000807064`],
     source: new XYZ({
-      url: '/water-quality-archive/api/maps/raster/v1/zxy/Light_3857/{z}/{x}/{y}.png',
+      url: `${baseUrl}/api/maps/raster/v1/zxy/Light_3857/{z}/{x}/{y}.png`,
     }),
     visible: false,
   });
@@ -36,7 +36,7 @@ export const initializeBasemapLayers = () => {
   const osMapsOutdoor = new TileLayer({
     // attributions: [`© Crown Copyright and Database Rights [insert year of creation] OS AC0000807064`],
     source: new XYZ({
-      url: '/water-quality-archive/api/maps/raster/v1/zxy/Outdoor_3857/{z}/{x}/{y}.png',
+      url: `${baseUrl}/api/maps/raster/v1/zxy/Outdoor_3857/{z}/{x}/{y}.png`,
     }),
     visible: false,
   });
@@ -50,7 +50,7 @@ export const initializeBasemapLayers = () => {
   const osMapsRoad = new TileLayer({
     // attributions: [`© Crown Copyright and Database Rights [insert year of creation] OS AC0000807064`],
     source: new XYZ({
-      url: '/water-quality-archive/api/maps/raster/v1/zxy/Road_3857/{z}/{x}/{y}.png',
+      url: `${baseUrl}/api/maps/raster/v1/zxy/Road_3857/{z}/{x}/{y}.png`,
     }),
     visible: false,
   });

package/src/utils/date.ts

@@ -0,0 +1,6 @@
+import { format, type DateArg } from 'date-fns';
+
+export const DEFAULT_DATE_FORMAT = 'yyyy-MM-dd';
+
+export const formatDate = (date: DateArg<Date>, pattern = DEFAULT_DATE_FORMAT) =>
+  format(date instanceof Date ? date : new Date(date), pattern);

package/src/utils/index.ts

@@ -1,3 +1,4 @@
 export * from './utils';
 export * from './auth';
 export * from './constants';
+export * from './date';