@tpzdsp/next-toolkit 1.7.0 → 1.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tpzdsp/next-toolkit",
-  "version": "1.7.0",
+  "version": "1.9.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",
@@ -163,6 +164,8 @@
     "eslint-plugin-react-refresh": "^0.4.20",
     "eslint-plugin-sonarjs": "^3.0.4",
     "eslint-plugin-storybook": "^9.0.18",
+    "focus-trap": "^7.6.5",
+    "focus-trap-react": "^11.0.4",
     "geojson": "^0.5.0",
     "globals": "^16.3.0",
     "husky": "^9.1.7",
@@ -206,6 +209,9 @@
     "@turf/turf": "^7.2.0",
     "@types/geojson": "^7946.0.16",
     "@types/jsonwebtoken": "^9.0.10",
+    "date-fns": "^4.1.0",
+    "focus-trap": "^7.6.5",
+    "focus-trap-react": "^11.0.4",
     "geojson": "^0.5.0",
     "jsonwebtoken": "^9.0.2",
     "next": "^15.4.2",
@@ -220,6 +226,12 @@
     "zod": "^4.1.8"
   },
   "peerDependenciesMeta": {
+    "@tanstack/react-query": {
+      "optional": true
+    },
+    "@better-fetch/fetch": {
+      "optional": true
+    },
     "@turf/turf": {
       "optional": true
     },
@@ -229,6 +241,15 @@
     "@types/jsonwebtoken": {
       "optional": true
     },
+    "date-fns": {
+      "optional": true
+    },
+    "focus-trap": {
+      "optional": true
+    },
+    "focus-trap-react": {
+      "optional": true
+    },
     "geojson": {
       "optional": true
     },
@@ -249,6 +270,9 @@
     },
     "react-select": {
       "optional": true
+    },
+    "zod": {
+      "optional": true
     }
   },
   "optionalDependencies": {

package/src/components/Card/Card.stories.tsx

@@ -1,56 +1,83 @@
+/* eslint-disable storybook/no-renderer-packages */
 import { FaChevronRight } from 'react-icons/fa6';
 
-/* eslint-disable storybook/no-renderer-packages */
-import type { Meta, StoryFn } from '@storybook/react';
+import type { Meta, StoryObj } from '@storybook/react';
 
-import { Card, type CardProps } from './Card';
+import { Card } from './Card';
+import { ExternalLink } from '../link/ExternalLink';
 import { Paragraph } from '../Paragraph/Paragraph';
 
-export default {
-  children: 'Card',
+const meta: Meta<typeof Card> = {
+  title: 'Components/Card',
   component: Card,
-} as Meta;
+  parameters: {
+    layout: 'padded',
+  },
+  tags: ['autodocs'],
+  argTypes: {
+    children: {
+      description: 'Content of the card',
+      control: false,
+    },
+    className: {
+      description: 'Additional TailwindCSS classes to apply',
+      control: 'text',
+    },
+  },
+  args: {
+    children: 'Hello, this is some simple text',
+  },
+};
+
+export default meta;
 
-const Template: StoryFn<CardProps> = (args) => <Card {...args} />;
+type Story = StoryObj<typeof Card>;
 
-export const JustText = Template.bind({});
-JustText.args = {
-  children: 'Hello, this is some simple text',
+export const Default: Story = {};
+
+export const ParagraphOfText: Story = {
+  args: {
+    children: <Paragraph>Hello, this is some simple text</Paragraph>,
+  },
 };
 
-export const ParagraphOfText = Template.bind({});
-ParagraphOfText.args = {
-  children: <p>Hello, this is some simple text</p>,
+export const ImageAndText: Story = {
+  args: {
+    children: (
+      <div>
+        <img
+          src="https://images.unsplash.com/photo-1563991655280-cb95c90ca2fb?w=500&auto=format&fit=crop&q=60&ixlib=rb-4.0.3&ixid=M3wxMjA3fDB8MHxzZWFyY2h8M3x8bm8lMjBjb3B5cmlnaHR8ZW58MHx8MHx8fDA%3D"
+          alt="Card"
+        />
+
+        <p>This is text about the image</p>
+      </div>
+    ),
+  },
 };
 
-export const ImageAndText = Template.bind({});
-ImageAndText.args = {
-  children: (
-    <div>
-      <img
-        src="https://images.unsplash.com/photo-1563991655280-cb95c90ca2fb?w=500&auto=format&fit=crop&q=60&ixlib=rb-4.0.3&ixid=M3wxMjA3fDB8MHxzZWFyY2h8M3x8bm8lMjBjb3B5cmlnaHR8ZW58MHx8MHx8fDA%3D"
-        alt="Card"
-      />
-
-      <p>This is text about the image</p>
-    </div>
-  ),
+export const ComplexChildren: Story = {
+  args: {
+    children: (
+      <>
+        <ExternalLink
+          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" />
+        </ExternalLink>
+
+        <Paragraph>Some descriptive text</Paragraph>
+      </>
+    ),
+  },
 };
 
-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>
-    </>
-  ),
+export const CustomStyling: Story = {
+  args: {
+    className: 'bg-blue-100 text-blue-800 p-4 rounded-lg shadow-lg',
+    children: 'Custom styled card',
+  },
 };

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

@@ -3,7 +3,7 @@ import type { Meta, StoryObj } from '@storybook/react';
 
 import { ErrorFallback } from './ErrorFallback';
 import { ApiError } from '../../errors/ApiError';
-import { HttpStatus } from '../../http';
+import { HttpStatus } from '../../http/constants';
 
 const meta = {
   title: 'Components/ErrorFallback',
@@ -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,18 @@
-import { type FallbackProps } from 'react-error-boundary';
+'use client';
+
+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 +20,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.stories.tsx

@@ -1,34 +1,53 @@
 /* eslint-disable storybook/no-renderer-packages */
-import type { Meta, StoryFn } from '@storybook/react';
+import type { Meta, StoryObj } from '@storybook/react';
 
-import { ErrorText, type ErrorTextProps } from './ErrorText';
+import { ErrorText } from './ErrorText';
+import { ExternalLink } from '../link/ExternalLink';
 
-export default {
-  children: 'Error text',
+const meta: Meta<typeof ErrorText> = {
+  title: 'Components/ErrorText',
   component: ErrorText,
-} as Meta;
+  parameters: {
+    layout: 'padded',
+  },
+  tags: ['autodocs'],
+  argTypes: {
+    children: {
+      description: 'The content to display for the error',
+      control: false,
+    },
+    className: {
+      description: 'Additional TailwindCSS classes to apply',
+      control: 'text',
+    },
+  },
+  args: {
+    children: 'Error message',
+  },
+};
 
-const Template: StoryFn<ErrorTextProps> = (args) => <ErrorText {...args} />;
+export default meta;
 
-export const DefaultError = Template.bind({});
-DefaultError.args = {
-  children: 'Error message',
-};
+type Story = StoryObj<typeof ErrorText>;
+
+export const Default: Story = {};
 
-export const CustomStyling = Template.bind({});
-CustomStyling.args = {
-  className: 'text-3xl',
-  children: 'Error message with large text',
+export const CustomStyling: Story = {
+  args: {
+    className: 'text-3xl',
+    children: 'Custom styled error message',
+  },
 };
 
-export const ComplexChildren = Template.bind({});
-ComplexChildren.args = {
-  children: (
-    <div>
-      Error message with link{' '}
-      <a className="underline text-link" href="/">
-        Link
-      </a>
-    </div>
-  ),
+export const ComplexChildren: Story = {
+  args: {
+    children: (
+      <div>
+        Error message with{' '}
+        <ExternalLink className="underline text-link" href="/">
+          Link
+        </ExternalLink>
+      </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':