@tpzdsp/next-toolkit 1.6.0 → 1.7.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.7.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",
@@ -182,9 +195,12 @@
     "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",
@@ -200,7 +216,8 @@
     "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": {
     "@turf/turf": {

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',
@@ -42,7 +42,7 @@ 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, 'Extra details'),
     resetErrorBoundary: mockReset,
   },
   parameters: {

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

@@ -1,7 +1,7 @@
 import { ErrorFallback } from './ErrorFallback';
 import { ApiError } from '../../errors';
+import { HttpStatus } from '../../http';
 import { render, screen, userEvent } from '../../test/renderers';
-import { Http } from '../../utils/http';
 import { identityFn } from '../../utils/utils';
 
 describe('ErrorFallback', () => {
@@ -23,7 +23,7 @@ describe('ErrorFallback', () => {
   });
 
   it('renders message and cause for ApiError instance', () => {
-    const apiError = new ApiError('Fake Reason', Http.InternalServerError);
+    const apiError = new ApiError('Fake Reason', HttpStatus.InternalServerError);
 
     render(<ErrorFallback error={apiError} resetErrorBoundary={identityFn} />);
 

package/src/components/ErrorBoundary/ErrorFallback.tsx

@@ -6,13 +6,15 @@ import { ApiError } from '../../errors/ApiError';
 
 export const ErrorFallback = ({ resetErrorBoundary, error }: FallbackProps) => {
   let message;
-  let cause = undefined;
+  let details = undefined;
+  let digest = undefined;
 
   if (error instanceof ApiError) {
     message = error.message;
-    cause = error.details;
+    details = error.details;
   } else if (error instanceof Error) {
-    ({ message, cause } = error);
+    message = error.message;
+    details = error.cause?.toString();
   } else {
     message = 'Unknown';
   }
@@ -20,10 +22,24 @@ export const ErrorFallback = ({ resetErrorBoundary, error }: FallbackProps) => {
   return (
     <div>
       <ErrorText>
-        <p>There was an error. (Reason: {message})</p>
-        {typeof cause === 'string' ? <p>Cause: {cause}</p> : null}
+        There was an error. <br />
+        Reason: {message}
       </ErrorText>
+      {details ? (
+        <span>
+          <br />
+
+          <details>
+            <summary>Details</summary>
 
+            <pre>{details}</pre>
+          </details>
+        </span>
+      ) : (
+        <></>
+      )}
+      <br />
+      Digest: {digest ?? 'No digest provided'}
       <Button onClick={resetErrorBoundary}>Try Again</Button>
     </div>
   );

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/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) => {

package/src/errors/ApiError.ts

@@ -1,33 +1,95 @@
 /* eslint-disable no-restricted-syntax */
 
-import { Http } from '../utils/http';
+import z from 'zod/v4';
 
-export class ApiError extends Error {
+import { HttpStatus, HttpStatusText } from '../http';
+
+/**
+ * Schema defining the JSON shape of error responses returned by a server. (The proxy is where
+ * the error is used the most, though it isn't unique to the proxy and may be used elsewhere).
+ *
+ * Note: This schema intentionally excludes the HTTP `status` field,
+ * as that value is carried in the HTTP response itself (via the status code)
+ * and in the in-memory {@link ApiError} class for internal use.
+ */
+export const ApiErrorSchema = z.object({
+  message: z.string(),
+  details: z.string().nullable(),
+});
+
+export type ApiErrorSchemaOutput = z.output<typeof ApiErrorSchema>;
+
+/**
+ * Represents an error that can be returned by an API or proxy endpoint.
+ *
+ * Use this class to consistently capture errors along with an HTTP status
+ * code and optional detailed message. This allows:
+ * - Returning structured errors from API handlers or internal proxies.
+ * - Setting the status code for the response when an error has occurred.
+ * - Including additional context in `details` for debugging.
+ *
+ * Note:
+ * - Although it contains the same members, this class is separate from {@link ApiErrorSchema}.
+ *   The schema defines the serialized JSON payload returned to clients, while this class
+ *   *also* includes meta information of the response, such as the HTTP status code.
+ *   The status code is typically only used internally inside the proxy (to forward status codes),
+ *   but it could be accessed if a request 1 made with `throw` set to `false.`
+ */
+export class ApiError extends Error implements z.output<typeof ApiErrorSchema> {
+  public readonly details: string | null;
+  public readonly digest: string;
   public readonly status: number;
-  public readonly code?: string;
-  public readonly details?: unknown;
+  // `true` if this class was reconstructed on the client from an response from the proxy
+  private readonly rehydrated: boolean;
 
-  constructor(message: string, status: number, code?: string, details?: unknown) {
+  constructor(
+    message: string,
+    status: number,
+    details?: string | null,
+    options?: { rehydrated?: boolean },
+  ) {
     super(message);
+
     this.name = 'ApiError';
     this.status = status;
-    this.code = code;
-    this.details = details;
+    this.details = details ?? null;
+    this.digest = crypto.randomUUID();
+    this.rehydrated = options?.rehydrated ?? false;
 
     // Maintains proper stack trace for where our error was thrown (only available on V8)
     if (Error.captureStackTrace) {
       Error.captureStackTrace(this, ApiError);
     }
+
+    this.logError();
+  }
+
+  private logError() {
+    const trimmedStack = this.stack
+      ?.split('\n')
+      // Filter out noisy frames but keep traces from toolkit for debugging
+      .filter((line) => !line.includes('node_modules') || line.includes('next-toolkit'))
+      .join('\n');
+
+    const prefix =
+      !this.rehydrated && typeof window !== 'undefined' ? 'Client API Error' : 'Server API Error';
+
+    console.error(
+      // eslint-disable-next-line sonarjs/no-nested-template-literals
+      `[${prefix}]: ${this.message}${this.details ? ` (${this.details})` : ''}. Digest: ${
+        this.digest
+      }\n${!this.rehydrated ? (trimmedStack ?? 'aa') : 'bb'}`,
+    );
   }
 
   // Helper method to check if it's a client error (4xx)
   get isClientError(): boolean {
-    return this.status >= Http.BadRequest && this.status < Http.InternalServerError;
+    return this.status >= HttpStatus.BadRequest && this.status < HttpStatus.InternalServerError;
   }
 
   // Helper method to check if it's a server error (5xx)
   get isServerError(): boolean {
-    return this.status >= Http.InternalServerError;
+    return this.status >= HttpStatus.InternalServerError;
   }
 
   // Convert to a plain object for JSON serialization
@@ -36,36 +98,48 @@ export class ApiError extends Error {
       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 badRequest(details?: string): ApiError {
+    return new ApiError(HttpStatusText.BadRequest, HttpStatus.BadRequest, details);
+  }
+
+  static notFound(details?: string): ApiError {
+    return new ApiError(HttpStatusText.NotFound, HttpStatus.NotFound, details);
   }
 
-  static notFound(message = 'Resource not found'): ApiError {
-    return new ApiError(message, Http.NotFound, 'NOT_FOUND');
+  static unauthorized(details?: string): ApiError {
+    return new ApiError(HttpStatusText.Unauthorized, HttpStatus.Unauthorized, details);
   }
 
-  static unauthorized(message = 'Unauthorized'): ApiError {
-    return new ApiError(message, Http.Unauthorized, 'UNAUTHORIZED');
+  static notAllowed(details?: string): ApiError {
+    return new ApiError(HttpStatusText.NotAllowed, HttpStatus.NotAllowed, details);
   }
 
-  static forbidden(message = 'Forbidden'): ApiError {
-    return new ApiError(message, Http.Forbidden, 'FORBIDDEN');
+  static notImplemented(details?: string): ApiError {
+    return new ApiError(HttpStatusText.NotImplemented, HttpStatus.NotImplemented, details);
   }
 
-  static internalServerError(message = 'Internal server error'): ApiError {
-    return new ApiError(message, Http.InternalServerError, 'INTERNAL_SERVER_ERROR');
+  static forbidden(details?: string): ApiError {
+    return new ApiError(HttpStatusText.Forbidden, HttpStatus.Forbidden, details);
+  }
+
+  static unprocessableContent(details?: string): ApiError {
+    return new ApiError(
+      HttpStatusText.UnprocessableContent,
+      HttpStatus.UnprocessableContent,
+      details,
+    );
   }
 
-  static fromResponse(response: Response, message?: string): ApiError {
+  static internalServerError(details?: string): ApiError {
     return new ApiError(
-      message ?? `HTTP ${response.status}: ${response.statusText}`,
-      response.status,
+      HttpStatusText.InternalServerError,
+      HttpStatus.InternalServerError,
+      details,
     );
   }
 }

package/src/http/constants.ts

@@ -0,0 +1,111 @@
+/**
+ * Use the {@link MimeTypes} type for a union type containing these mime types.
+ */
+export const MimeType = {
+  Json: 'application/json',
+  JsonLd: 'application/ld+json',
+  GeoJson: 'application/geo+json',
+  Png: 'image/png',
+  XJsonLines: 'application/x-jsonlines',
+  Csv: 'text/csv',
+  Form: 'application/x-www-form-urlencoded',
+  Text: 'text/plain',
+} as const;
+
+/**
+ * Use the {@link MimeType} object for named constants of each mime type.
+ */
+export type MimeTypes = (typeof MimeType)[keyof typeof MimeType];
+
+/**
+ * Returns `true` if the mime type is a non-streamed JSON mime type (I.E. not JSON X-Lines).
+ */
+export const isJsonMimeType = (mime: MimeTypes | string | null): boolean => {
+  return ([MimeType.Json, MimeType.GeoJson, MimeType.JsonLd] as string[]).includes(mime ?? '');
+};
+
+/**
+ * Returns `true` if the mime type is a plain-text mime type.
+ */
+export const isTextMimeType = (mime: MimeTypes | string | null): boolean => {
+  return ([MimeType.Text, MimeType.Csv] as string[]).includes(mime ?? '');
+};
+
+/**
+ * Use the {@link HttpStatuses} type for a union type containing these status codes.
+ *
+ * Use the {@link HttpStatusText} object for the status text represented by each code.
+ */
+export const HttpStatus = {
+  Ok: 200,
+  Created: 201,
+  NoContent: 204,
+  BadRequest: 400,
+  Unauthorized: 401,
+  Forbidden: 403,
+  NotFound: 404,
+  NotAllowed: 405,
+  UnprocessableContent: 422,
+  InternalServerError: 500,
+  NotImplemented: 501,
+} as const;
+
+/**
+ * Use the {@link HttpStatus} object for named constants of each status code.
+ */
+export type HttpStatuses = (typeof HttpStatus)[keyof typeof HttpStatus];
+
+/**
+ * Status texts for each status code.
+ */
+export const HttpStatusText = {
+  Ok: 'OK',
+  Created: 'Created',
+  NoContent: 'No Content',
+  BadRequest: 'Bad Request',
+  Unauthorized: 'Unauthorized',
+  Forbidden: 'Forbidden',
+  NotFound: 'Not Found',
+  NotAllowed: 'Method Not Allowed',
+  UnprocessableContent: 'Unprocessable Content',
+  InternalServerError: 'Internal Server Error',
+  NotImplemented: 'Not Implemented',
+} as const;
+
+/**
+ * Use the {@link HttpMethods} type for a union type containing these method verbs.
+ */
+export const HttpMethod = {
+  Get: 'get',
+  Post: 'post',
+  Put: 'put',
+  Patch: 'patch',
+  Delete: 'delete',
+} as const;
+
+/**
+ * Use the {@link HttpMethod} object for named constants of each method verb.
+ */
+export type HttpMethods = (typeof HttpMethod)[keyof typeof HttpMethod];
+
+/**
+ * Use the {@link Headers} type for a union type containing these headers.
+ */
+export const Header = {
+  ContentType: 'Content-Type',
+  ContentDisposition: 'Content-Disposition',
+  Accept: 'Accept',
+  AcceptCrs: 'Accept-Crs',
+  CsvHeader: 'CSV-Header',
+  XTotalItems: 'X-Total-Items',
+  XRequestId: 'X-Request-ID',
+} as const;
+
+/**
+ * Use the {@link Header} object for named constants of each header.
+ */
+export type Headers = (typeof Header)[keyof typeof Header];
+
+// Special types used for downloading files via a `POST` request
+export const SPECIAL_FORM_DATA_TYPE = '_type';
+export const SPECIAL_FORM_DOWNLOAD_POST = 'file-download';