@tpzdsp/next-toolkit 1.5.0 → 1.7.0

package/src/components/SlidingPanel/SlidingPanel.tsx

@@ -1,6 +1,8 @@
 'use client';
 
-import { useState, useEffect, type ReactNode, useRef, useMemo } from 'react';
+import { useState, useEffect, type ReactNode, useRef, useMemo, useCallback } from 'react';
+
+import { KeyboardKeys } from '../../utils';
 
 type Position = 'center-left' | 'center-right' | 'center-top' | 'center-bottom';
 
@@ -11,6 +13,9 @@ export type SlidingPanelProps = {
   defaultOpen?: boolean;
 };
 
+const TRAP_SELECTORS =
+  'a[href]:not([aria-hidden="true"]):not([hidden]), button:not([disabled]):not([aria-hidden="true"]):not([hidden]), input:not([disabled]):not([aria-hidden="true"]):not([hidden]), textarea:not([disabled]):not([aria-hidden="true"]):not([hidden]), select:not([disabled]):not([aria-hidden="true"]):not([hidden]), [tabindex]:not([tabindex="-1"]):not([aria-hidden="true"]):not([hidden])';
+
 export const SlidingPanel = ({
   children,
   tabLabel = 'Open',
@@ -20,67 +25,16 @@ export const SlidingPanel = ({
   const [isVisible, setIsVisible] = useState(defaultOpen);
   const [panelDimensions, setPanelDimensions] = useState({ width: 0, height: 0 });
   const panelRef = useRef<HTMLDivElement>(null);
-  const toggleBtnRef = useRef<HTMLButtonElement>(null);
-
-  // Focus trap: cycle focus within panel when open
-  useEffect(() => {
-    if (!isVisible || !panelRef.current) {
-      return;
-    }
-
-    const panel = panelRef.current;
-    const focusableSelectors = [
-      'a[href]',
-      'button:not([disabled])',
-      'textarea:not([disabled])',
-      'input:not([disabled])',
-      'select:not([disabled])',
-      '[tabindex]:not([tabindex="-1"])',
-    ];
-    const getFocusable = () =>
-      Array.from(panel.querySelectorAll<HTMLElement>(focusableSelectors.join(','))).filter(
-        (el) => !el.hasAttribute('disabled') && !el.getAttribute('aria-hidden'),
-      );
-
-    const handleKeyDown = (e: KeyboardEvent) => {
-      if (e.key === 'Escape') {
-        setIsVisible(false);
-        // Return focus to toggle button after closing
-        toggleBtnRef.current?.focus();
-      }
-
-      if (e.key === 'Tab') {
-        const focusableEls = getFocusable();
-
-        if (focusableEls.length === 0) {
-          return;
-        }
-
-        const first = focusableEls[0];
-        const last = focusableEls[focusableEls.length - 1];
-
-        if (!e.shiftKey && document.activeElement === last) {
-          e.preventDefault();
-          first.focus();
-        } else if (e.shiftKey && document.activeElement === first) {
-          e.preventDefault();
-          last.focus();
-        }
-      }
-    };
-
-    panel.addEventListener('keydown', handleKeyDown);
-    // Focus the first focusable element in the panel
-    const focusableEls = getFocusable();
+  const triggerRef = useRef<HTMLElement | null>(null); // store previously focused element
 
-    if (focusableEls.length) {
-      focusableEls[0].focus();
-    }
+  const openPanel = () => {
+    triggerRef.current = document.activeElement as HTMLElement;
+    setIsVisible(true);
+  };
 
-    return () => {
-      panel.removeEventListener('keydown', handleKeyDown);
-    };
-  }, [isVisible]);
+  const closePanel = useCallback(() => {
+    setIsVisible(false);
+  }, []);
 
   // Measure panel dimensions when visible
   useEffect(() => {
@@ -112,44 +66,81 @@ export const SlidingPanel = ({
     }
   }, [isVisible, panelDimensions.height, panelDimensions.width]);
 
+  // move focus into panel when opened, restore focus to correct element when closed
+  useEffect(() => {
+    if (isVisible && panelRef.current) {
+      const els = Array.from(panelRef.current.querySelectorAll<HTMLElement>(TRAP_SELECTORS));
+
+      if (els.length > 0) {
+        els[0].focus();
+      } else {
+        panelRef.current.focus();
+      }
+    } else if (!isVisible && triggerRef.current) {
+      triggerRef.current.focus();
+    }
+  }, [isVisible]);
+
+  // trap focus while open
   useEffect(() => {
-    if (!panelRef.current) {
+    if (!isVisible || !panelRef.current) {
       return;
     }
 
-    const focusableSelectors = [
-      'a[href]',
-      'button:not([disabled])',
-      'textarea:not([disabled])',
-      'input:not([disabled])',
-      'select:not([disabled])',
-      '[tabindex]:not([tabindex="-1"])',
-    ];
-    const focusableEls = Array.from(
-      panelRef.current.querySelectorAll<HTMLElement>(focusableSelectors.join(',')),
-    );
-
-    if (!isVisible) {
-      // Remove from tab order
-      focusableEls.forEach((el) => {
-        el.dataset.prevTabIndex = el.getAttribute('tabindex') ?? '';
-        el.setAttribute('tabindex', '-1');
-      });
-    } else {
-      // Restore previous tabIndex
-      focusableEls.forEach((el) => {
-        if (el.dataset.prevTabIndex !== undefined) {
-          if (el.dataset.prevTabIndex === '') {
-            el.removeAttribute('tabindex');
-          } else {
-            el.setAttribute('tabindex', el.dataset.prevTabIndex);
-          }
+    const panel = panelRef.current;
 
-          delete el.dataset.prevTabIndex;
-        }
-      });
-    }
-  }, [isVisible]);
+    const moveFocus = (direction: 'next' | 'prev') => {
+      const els = Array.from(panel.querySelectorAll<HTMLElement>(TRAP_SELECTORS));
+
+      if (!els.length) {
+        panel.focus();
+
+        return true;
+      }
+
+      const first = els[0];
+      const last = els[els.length - 1];
+      const active = document.activeElement;
+
+      if (direction === 'next' && active === last) {
+        first.focus();
+
+        return true;
+      }
+
+      if (direction === 'prev' && active === first) {
+        last.focus();
+
+        return true;
+      }
+
+      return false;
+    };
+
+    const handleKey = (event: KeyboardEvent) => {
+      if (event.key === KeyboardKeys.Escape) {
+        event.preventDefault();
+        closePanel();
+
+        return;
+      }
+
+      if (event.key !== KeyboardKeys.Tab) {
+        return;
+      }
+
+      // only if focus was moved do we prevent the default behaviour
+      if (moveFocus(event.shiftKey ? 'prev' : 'next')) {
+        event.preventDefault();
+      }
+    };
+
+    panel.addEventListener('keydown', handleKey);
+
+    return () => {
+      panel.removeEventListener('keydown', handleKey);
+    };
+  }, [closePanel, isVisible]);
 
   const panelBase =
     'absolute bg-white shadow-lg p-4 flex flex-col transition-transform duration-300 ease-in-out overflow-auto z-30';
@@ -211,12 +202,11 @@ export const SlidingPanel = ({
   }, [isVisible, panelDimensions.height, panelDimensions.width, position]);
 
   return (
-    <div className="absolute inset-0 overflow-hidden pointer-events-none z-30">
+    <div className="absolute inset-0 z-30 overflow-hidden pointer-events-none sliding-panel">
       <button
-        ref={toggleBtnRef}
         className={`pointer-events-auto ${buttonPosition} bg-gray-700 text-white z-40 focus-yellow`}
         style={getButtonStyle}
-        onClick={() => setIsVisible((prev) => !prev)}
+        onClick={() => (isVisible ? closePanel() : openPanel())}
         aria-expanded={isVisible}
         aria-controls="sliding-panel"
       >
@@ -225,9 +215,11 @@ export const SlidingPanel = ({
 
       <div
         ref={panelRef}
+        tabIndex={-1}
         id="sliding-panel"
         className={`${panelBase} ${panelLayout} pointer-events-auto`}
         aria-hidden={!isVisible}
+        inert={!isVisible}
       >
         <div className="mt-4">{children}</div>
       </div>

package/src/components/backToTop/BackToTop.tsx

@@ -4,6 +4,8 @@ import { type KeyboardEvent, useCallback, useEffect, useState } from 'react';
 
 import { LuArrowUp } from 'react-icons/lu';
 
+import { KeyboardKeys } from '../../utils';
+
 export type BackToTopProps = {
   /** Scroll threshold in pixels before button appears */
   threshold?: number;
@@ -87,7 +89,7 @@ export const BackToTop = ({
   // Handle keyboard interaction
   const handleKeyDown = useCallback(
     (event: KeyboardEvent<HTMLButtonElement>) => {
-      if (event.key === 'Enter' || event.key === ' ') {
+      if (event.key === KeyboardKeys.Enter || event.key === KeyboardKeys.Space) {
         event.preventDefault();
         scrollToTop();
       }

package/src/components/dropdown/useDropdownMenu.ts

@@ -11,6 +11,7 @@ import {
 } from 'react';
 
 import type { ExtendProps } from '../../types/utils';
+import { KeyboardKeys } from '../../utils';
 
 /**
  * The current state of the menu
@@ -117,7 +118,11 @@ export const useDropdownMenu = (itemCount: number): DropdownMenuHook => {
   useEffect(() => {
     // handles exiting the menu when the `Escape` key is pressed
     const escapeExitMenuHandler = (event: KeyboardEvent) => {
-      if (event.key === 'Escape' && document.activeElement && isMenuItem(document.activeElement)) {
+      if (
+        event.key === KeyboardKeys.Escape &&
+        document.activeElement &&
+        isMenuItem(document.activeElement)
+      ) {
         event.preventDefault();
 
         setIsOpen(false);
@@ -166,14 +171,14 @@ export const useDropdownMenu = (itemCount: number): DropdownMenuHook => {
       onPointerUp: () => setIsOpen(!isOpen),
       onKeyDown: (event) => {
         //  space and enter act more like clicking and can toggle the menu open/closed
-        if (event.key === ' ' || event.key === 'Enter') {
+        if (event.key === KeyboardKeys.Space || event.key === KeyboardKeys.Enter) {
           event.preventDefault();
 
           setIsOpen(!isOpen);
         }
 
         // the down arrow should open the menu
-        if (event.key === 'ArrowDown') {
+        if (event.key === KeyboardKeys.ArrowDown) {
           event.preventDefault();
 
           if (!isOpen) {
@@ -208,7 +213,7 @@ export const useDropdownMenu = (itemCount: number): DropdownMenuHook => {
         let focusIndex = currentFocusIndex.current;
 
         // close the menu if you "select" an item
-        if (event.key === ' ' || event.key === 'Enter') {
+        if (event.key === KeyboardKeys.Space || event.key === KeyboardKeys.Enter) {
           event.preventDefault();
 
           // we just called `preventDefault` so we need to manually click it otherwise nothing will happen
@@ -220,11 +225,11 @@ export const useDropdownMenu = (itemCount: number): DropdownMenuHook => {
 
         if (focusIndex !== null) {
           // arrow keys should cycle through each item in the menu
-          if (event.key === 'ArrowDown') {
+          if (event.key === KeyboardKeys.ArrowDown) {
             event.preventDefault();
 
             focusIndex += 1;
-          } else if (event.key === 'ArrowUp') {
+          } else if (event.key === KeyboardKeys.ArrowUp) {
             event.preventDefault();
 
             focusIndex -= 1;

package/src/components/skipLink/SkipLink.tsx

@@ -1,5 +1,6 @@
 'use client';
 
+import { KeyboardKeys } from '../../utils';
 import { Link } from '../link/Link';
 
 export type SkipLinkProps = {
@@ -21,12 +22,12 @@ export const SkipLink = ({ mainContentId = 'main-content' }: SkipLinkProps) => {
   return (
     <nav aria-label="Skip navigation">
       <Link
-        className="bg-focus focus:relative focus:top-0 w-full absolute -top-full text-black
-          visited:text-black hover:text-black p-3 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) => {
-          if (event.key === 'Enter' || event.key === ' ') {
+          if (event.key === KeyboardKeys.Enter || event.key === KeyboardKeys.Space) {
             event.preventDefault(); // Prevent default scroll/jump
             handleActivate();
           }

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';