@tpzdsp/next-toolkit 1.6.0 → 1.8.0

package/README.md

@@ -262,7 +262,7 @@ yarn preview
 
 ## Local Development with Yalc
 
-This library works perfectly with `yalc` for local testing before publishing to npm. Since we distribute source files, changes are reflected immediately.
+This library works well with `yalc` for local testing before publishing to npm. However, **hot reloading doesn't work reliably** with yalc - you'll need to manually push changes and restart your development server.
 
 ### Setup Yalc (one-time)
 
@@ -275,8 +275,6 @@ npm install -g yalc
 
 ```bash
 # In this library directory
-yarn yalc:publish
-# or
 yalc publish
 ```
 
@@ -284,9 +282,9 @@ yalc publish
 
 ```bash
 # In your Next.js app directory
-yalc add @your-org/nextjs-library
+yalc add @tpzdsp/next-toolkit
 
-# Install dependencies (yalc creates a symlink-like structure)
+# Install dependencies
 yarn install
 ```
 
@@ -297,69 +295,48 @@ Add to your `next.config.js`:
 ```js
 /** @type {import('next').NextConfig} */
 const nextConfig = {
-  transpilePackages: ['@your-org/nextjs-library'],
-  // Enable if you want faster refresh during development
+  transpilePackages: ['@tpzdsp/next-toolkit'],
   experimental: {
-    externalDir: true,
+    externalDir: true, // May help with yalc symlinks
   },
 };
 
 module.exports = nextConfig;
 ```
 
-### Development Workflow
+### Development Workflow (Manual Process)
 
 ```bash
-# 1. Make changes to the library
-# 2. Push changes to apps using the library
-yarn yalc:push
-# or
+# 1. Make changes to the library components/hooks/etc.
+
+# 2. Push changes to connected apps
 yalc push
 
-# 3. Your Next.js app will automatically pick up the changes!
+# 3. In your test app, clear Next.js cache and restart
+rm -rf .next && yarn dev
 ```
 
+### Why No Hot Reloading?
+
+- **Symlink Issues**: Next.js file watching doesn't reliably detect changes in yalc-linked packages
+- **Module Resolution**: TypeScript and bundler caching can prevent updates from being picked up
+- **Source Distribution**: While our source distribution strategy helps with tree-shaking, it doesn't solve the hot reload problem with yalc
+
 ### Removing from Test App
 
 ```bash
 # In your Next.js app directory
-yalc remove @your-org/nextjs-library
+yalc remove @tpzdsp/next-toolkit
 yarn install
 ```
 
-### Benefits with Source Distribution
+### Benefits Despite Manual Process
 
-- ✅ **Instant Changes**: Since we distribute source files, changes appear immediately
+- ✅ **Real Environment Testing**: Test in an actual Next.js app setup
 - ✅ **Full TypeScript**: Complete type checking and IntelliSense
-- ✅ **Tree Shaking**: Your app's bundler handles optimization
-- ✅ **Hot Reload**: Works with Next.js development server
-- ✅ **No Build Step**: No need to rebuild the library for every change
-
-## 🚀 Quick Yalc Workflow
-
-### Library Development (this repo):
-
-```bash
-# First time setup
-yalc publish
-
-# After making changes
-yalc push  # Pushes to all connected apps
-```
-
-### In Your Next.js Test App:
-
-```bash
-# Add the library
-yalc add @your-org/nextjs-library
-yarn install
-
-# Configure next.config.js (transpilePackages: ['@your-org/nextjs-library'])
-
-# Remove when done testing
-yalc remove @your-org/nextjs-library
-yarn install
-```
+- ✅ **Tree Shaking**: Your app's bundler handles optimization  
+- ✅ **No Publishing**: Test without polluting npm registry
+- ❌ **Manual Refresh Required**: No automatic hot reloading
 
 ## 🛠️ Adding New Components
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tpzdsp/next-toolkit",
-  "version": "1.6.0",
+  "version": "1.8.0",
   "description": "A reusable React component library for Next.js applications",
   "type": "module",
   "private": false,
@@ -38,6 +38,11 @@
       "import": "./src/utils/http.ts",
       "require": "./src/utils/http.ts"
     },
+    "./utils/schema": {
+      "types": "./src/utils/schema.ts",
+      "import": "./src/utils/schema.ts",
+      "require": "./src/utils/schema.ts"
+    },
     "./components": {
       "types": "./src/components/index.ts",
       "import": "./src/components/index.ts",
@@ -48,6 +53,11 @@
       "import": "./src/components/select/index.ts",
       "require": "./src/components/select/index.ts"
     },
+    "./http": {
+      "types": "./src/http/index.ts",
+      "import": "./src/http/index.ts",
+      "require": "./src/http/index.ts"
+    },
     "./map": {
       "types": "./src/map/index.ts",
       "import": "./src/map/index.ts",
@@ -104,6 +114,7 @@
     "release": "semantic-release"
   },
   "devDependencies": {
+    "@better-fetch/fetch": "1.1.19-beta.1",
     "@eslint/js": "^9.30.1",
     "@semantic-release/changelog": "^6.0.3",
     "@semantic-release/git": "^10.0.1",
@@ -113,11 +124,13 @@
     "@storybook/addon-interactions": "^8.6.14",
     "@storybook/addon-links": "8.6.14",
     "@storybook/addon-onboarding": "8.6.14",
+    "@storybook/preview-api": "^8.6.14",
     "@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",
+    "@tanstack/react-query": "^5.89.0",
     "@testing-library/dom": "^10.4.0",
     "@testing-library/jest-dom": "^6.6.3",
     "@testing-library/react": "^16.3.0",
@@ -137,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",
@@ -182,14 +196,18 @@
     "util": "^0.12.5",
     "vite": "^7.0.4",
     "vite-plugin-dts": "^4.5.4",
-    "vitest": "^3.2.4"
+    "vitest": "^3.2.4",
+    "zod": "^4.1.8"
   },
   "peerDependencies": {
+    "@better-fetch/fetch": "1.1.19-beta.1",
+    "@tanstack/react-query": "^5.89.0",
     "@testing-library/react": "^16.0.0",
     "@testing-library/user-event": "^14.6.1",
     "@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",
@@ -200,9 +218,16 @@
     "react": "^19.1.0",
     "react-dom": "^19.1.0",
     "react-error-boundary": "^6.0.0",
-    "react-icons": "^5.5.0"
+    "react-icons": "^5.5.0",
+    "zod": "^4.1.8"
   },
   "peerDependenciesMeta": {
+    "@tanstack/react-query": {
+      "optional": true
+    },
+    "@better-fetch/fetch": {
+      "optional": true
+    },
     "@turf/turf": {
       "optional": true
     },
@@ -212,6 +237,9 @@
     "@types/jsonwebtoken": {
       "optional": true
     },
+    "date-fns": {
+      "optional": true
+    },
     "geojson": {
       "optional": true
     },
@@ -232,6 +260,9 @@
     },
     "react-select": {
       "optional": true
+    },
+    "zod": {
+      "optional": true
     }
   },
   "optionalDependencies": {

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 { Http } from '../../utils/http';
+import { HttpStatus } from '../../http';
 
 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', Http.InternalServerError, undefined, '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 { render, screen, userEvent } from '../../test/renderers';
-import { Http } from '../../utils/http';
+import { HttpStatus } from '../../http';
+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', Http.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,30 +1,84 @@
-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 cause = undefined;
+  let details = undefined;
+  let digest = undefined;
 
   if (error instanceof ApiError) {
     message = error.message;
-    cause = error.details;
+    details = error.details;
+    digest = error.digest;
   } else if (error instanceof Error) {
-    ({ message, cause } = 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>
-        <p>There was an error. (Reason: {message})</p>
-        {typeof cause === 'string' ? <p>Cause: {cause}</p> : null}
-      </ErrorText>
+    <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>
 
-      <Button onClick={resetErrorBoundary}>Try Again</Button>
+      {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>
+      )}
     </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/Modal/Modal.tsx

@@ -36,7 +36,8 @@ export const Modal = ({ isOpen, onClose, children }: ModalProps) => {
         // dialog elements do have a key handler as you can close them with `Escape`, so this can be ignored
         // eslint-disable-next-line jsx-a11y/click-events-have-key-events, jsx-a11y/no-noninteractive-element-interactions
         <dialog
-          className="fixed inset-0 flex items-center justify-center w-full h-full m-0 bg-transparent backdrop:bg-black/50"
+          className="fixed inset-0 flex items-center justify-center w-full h-full m-0 bg-transparent
+            backdrop:bg-black/50"
           ref={modalRef}
           onCancel={(event) => {
             event.preventDefault();

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/components/skipLink/SkipLink.tsx

@@ -22,7 +22,8 @@ export const SkipLink = ({ mainContentId = 'main-content' }: SkipLinkProps) => {
   return (
     <nav aria-label="Skip navigation">
       <Link
-        className="absolute w-full p-3 text-black bg-focus focus:relative focus:top-0 -top-full visited:text-black hover:text-black skip-link"
+        className="absolute w-full p-3 text-black bg-focus focus:relative focus:top-0 -top-full
+          visited:text-black hover:text-black skip-link"
         href={`#${mainContentId}`}
         onClick={handleActivate}
         onKeyDown={(event) => {