@tpzdsp/next-toolkit 1.1.0 → 1.2.1

package/src/map/basemaps.ts

@@ -0,0 +1,79 @@
+import type { StaticImageData } from 'next/image';
+import TileLayer from 'ol/layer/Tile';
+import OSM from 'ol/source/OSM';
+import XYZ from 'ol/source/XYZ';
+
+import OsImage from './images/basemaps/OS.png';
+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 = () => {
+  const osmLayer = new TileLayer({
+    preload: Infinity,
+    source: new OSM(),
+    visible: true,
+  });
+
+  osmLayer.set('name', 'OSM');
+  osmLayer.set('basemap', true);
+  const osImageData = OsImage as unknown as StaticImageData;
+
+  osmLayer.set('image', osImageData.src);
+
+  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',
+    }),
+    visible: false,
+  });
+
+  osMapsLight.set('name', 'OS Maps Light');
+  osMapsLight.set('basemap', true);
+  osMapsLight.set('image', osImageData.src);
+
+  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',
+    }),
+    visible: false,
+  });
+
+  osMapsOutdoor.set('name', 'OS Maps Outdoor');
+  osMapsOutdoor.set('basemap', true);
+  const streetsImageData = StreetsImage as unknown as StaticImageData;
+
+  osMapsOutdoor.set('image', streetsImageData.src);
+
+  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',
+    }),
+    visible: false,
+  });
+
+  osMapsRoad.set('name', 'OS Maps Road');
+  osMapsRoad.set('basemap', true);
+  const satelliteMapTilerImageData = SatelliteMapTilerImage as unknown as StaticImageData;
+
+  osMapsRoad.set('image', satelliteMapTilerImageData.src);
+
+  const worldImagery = new TileLayer({
+    source: new XYZ({
+      url: 'https://server.arcgisonline.com/ArcGIS/rest/services/World_Imagery/MapServer/tile/{z}/{y}/{x}',
+      maxZoom: 19,
+    }),
+    visible: false,
+  });
+
+  worldImagery.set('name', 'ESRI World Imagery');
+  worldImagery.set('basemap', true);
+  const satelliteImageData = SatelliteImage as unknown as StaticImageData;
+
+  worldImagery.set('image', satelliteImageData.src);
+
+  return [osmLayer, osMapsLight, osMapsOutdoor, osMapsRoad, worldImagery];
+};

package/src/map/geocoder.ts

@@ -0,0 +1,61 @@
+import { Map } from 'ol';
+import { transformExtent } from 'ol/proj';
+import Geocoder from 'ol-geocoder';
+
+import { EPSG_3857, EPSG_4326 } from './geometries';
+import { osOpenNamesSearch } from './osOpenNamesSearch';
+
+type AddressChosenEvent = {
+  place: {
+    lon: number;
+    lat: number;
+    bbox?: [number, number, number, number]; // [minLon, minLat, maxLon, maxLat]
+    address: {
+      name: string;
+      city?: string;
+      state?: string;
+      country?: string;
+    };
+  };
+};
+
+export const initializeGeocoder = (apiKey: string, geoCoderUrl: string, map: Map) => {
+  if (!apiKey) {
+    console.warn('No API key provided for geocoder initialization.');
+
+    throw new Error(
+      'API key is required for geocoder initialization. Please provide a valid API key.',
+    );
+  }
+
+  const provider = osOpenNamesSearch({
+    url: geoCoderUrl,
+  });
+
+  const geocoder = new Geocoder('nominatim', {
+    provider,
+    key: apiKey,
+    lang: 'en',
+    placeholder: 'Search for ...',
+    targetType: 'text-input',
+    keepOpen: false,
+    preventMarker: true,
+    debug: true,
+  });
+
+  // Since we provide a bbox in the custom provider response,
+  // we also need to handle the address chosen event.
+  geocoder.on('addresschosen', (event: AddressChosenEvent) => {
+    if (event.place.bbox) {
+      const extent3857 = transformExtent(event.place.bbox, EPSG_4326, EPSG_3857);
+
+      map.getView().fit(extent3857, {
+        duration: 500,
+        padding: [50, 50, 50, 50],
+        maxZoom: 18,
+      });
+    }
+  });
+
+  return geocoder;
+};

package/src/map/geometries.ts

@@ -0,0 +1,60 @@
+import { transform } from 'ol/proj';
+import proj4 from 'proj4';
+
+import './projections';
+
+export const EPSG_27700 = 'EPSG:27700';
+export const EPSG_4326 = 'EPSG:4326';
+export const EPSG_3857 = 'EPSG:3857';
+const POINT_LENGTH = 2;
+const BBOX_LENGTH = 4;
+
+/**
+ * Converts coordinates from EPSG:27700 (OSGB36) to EPSG:4326 (WGS84).
+ * Supports single points (x, y) or bounding boxes (xmin, ymin, xmax, ymax).
+ *
+ * @param coords - Either an [x, y] array or a [xmin, ymin, xmax, ymax] array.
+ *
+ * @returns Converted coordinates in EPSG:4326.
+ */
+export const transform27700to4326 = (
+  coords: [number, number] | [number, number, number, number],
+) => {
+  if (coords.length === POINT_LENGTH) {
+    // Single point transformation
+    return proj4(EPSG_27700, EPSG_4326, coords);
+  }
+
+  if (coords.length === BBOX_LENGTH) {
+    // Bounding box transformation (SW and NE corners)
+    const [xmin, ymin, xmax, ymax] = coords;
+
+    const [swLon, swLat] = proj4(EPSG_27700, EPSG_4326, [xmin, ymin]);
+    const [neLon, neLat] = proj4(EPSG_27700, EPSG_4326, [xmax, ymax]);
+
+    const minLon = Math.min(swLon, neLon);
+    const maxLon = Math.max(swLon, neLon);
+    const minLat = Math.min(swLat, neLat);
+    const maxLat = Math.max(swLat, neLat);
+
+    return [minLon, minLat, maxLon, maxLat]; // Correct bbox
+  }
+
+  throw new Error('Invalid coordinate input. Must be [x, y] or [xmin, ymin, xmax, ymax].');
+};
+
+/**
+ * Transforms polygon coordinates from one projection to another.
+ *
+ * @param coords - A polygon in the format [[[x, y], ...]].
+ * @param from - Source projection (e.g., 'EPSG:27700').
+ * @param to - Target projection (e.g., 'EPSG:3857').
+ * @returns Transformed polygon coordinates.
+ */
+export const transformPolygonCoords = (
+  coords: number[][][],
+  from: string,
+  to: string,
+): number[][][] => {
+  return coords.map((ring) => ring.map(([x, y]) => transform([x, y], from, to)));
+};

package/src/map/index.ts

@@ -0,0 +1,10 @@
+export * from './basemaps';
+export * from './geocoder';
+export * from './geometries';
+export * from './LayerSwitcherControl';
+export * from './map';
+export * from './Map';
+export * from './MapContext';
+export * from './osOpenNamesSearch';
+export * from './Popup';
+export * from './projections';

package/src/map/map.ts

@@ -0,0 +1,40 @@
+import { Map } from 'ol';
+
+import type { PopupDirection } from '../types/map';
+
+export const LAYER_NAMES = {
+  Aoi: 'aoi-layer',
+  Boundary: 'boundary-layer',
+  SamplingPoints: 'sampling-points-layer',
+};
+
+const POPUP_WIDTH = 300;
+const POPUP_HEIGHT = 300;
+
+export const getPopupPositionClass = (coordinate: number[], map: Map): PopupDirection => {
+  const pixel = map.getPixelFromCoordinate(coordinate);
+  const [x, y] = pixel;
+
+  const isTop = y > POPUP_HEIGHT;
+  const isBottom = y < POPUP_HEIGHT;
+  const isLeft = x > POPUP_WIDTH;
+  const isRight = x < POPUP_WIDTH;
+
+  if (isTop && isLeft) {
+    return 'top-left';
+  }
+
+  if (isBottom && isLeft) {
+    return 'bottom-left';
+  }
+
+  if (isBottom && isRight) {
+    return 'bottom-right';
+  }
+
+  if (isTop && isRight) {
+    return 'top-right';
+  }
+
+  return 'bottom-right';
+};

package/src/map/osOpenNamesSearch.ts

@@ -0,0 +1,54 @@
+import type { FeatureCollection } from 'geojson';
+
+export type SearchOption = {
+  url?: string;
+};
+
+/**
+ * Custom provider for OS OpenNames search.
+ */
+export const osOpenNamesSearch = (options?: SearchOption) => {
+  const { url } = options ?? {};
+
+  return {
+    /**
+     * Get the URL and parameters needed for the request.
+     *
+     * @param {object} opt - Options object containing the query.
+     */
+    getParameters: (opt: { query: string }) => {
+      return {
+        url,
+        params: {
+          query: opt.query,
+        },
+      };
+    },
+
+    /**
+     * Process the API response and format it for ol-geocoder.
+     *
+     * @param {object} results - OS Names API response.
+     */
+    handleResponse: (response: FeatureCollection) => {
+      const { features } = response;
+
+      if (!features?.length) {
+        return [];
+      }
+
+      return features.map((feature) => {
+        if (feature.geometry.type === 'Point') {
+          return {
+            lon: feature.geometry.coordinates[0],
+            lat: feature.geometry.coordinates[1],
+            address: feature?.properties?.address,
+            bbox: feature.bbox,
+          };
+        }
+
+        console.error('Geometry type is not Point');
+      });
+    },
+  };
+};

package/src/map/projections.ts

@@ -0,0 +1,14 @@
+import { register } from 'ol/proj/proj4';
+import proj4 from 'proj4';
+
+// Define EPSG:27700 (British National Grid)
+proj4.defs(
+  'EPSG:27700',
+  '+proj=tmerc +lat_0=49 +lon_0=-2 +k=0.9996012717 ' +
+    '+x_0=400000 +y_0=-100000 +ellps=airy ' +
+    '+towgs84=446.448,-125.157,542.06,0.15,0.247,0.842,-20.489 ' +
+    '+units=m +no_defs',
+);
+
+// Register the projection with OpenLayers
+register(proj4);

package/src/ol-geocoder.d.ts

@@ -0,0 +1 @@
+declare module 'ol-geocoder';

package/src/test/index.ts

@@ -0,0 +1 @@
+export * from './renderers';

package/src/types/api.ts

@@ -0,0 +1,52 @@
+// API related types
+export type ApiResponse<T = unknown> = {
+  data: T;
+  success: boolean;
+  message?: string;
+  errors?: Record<string, string[]>;
+};
+
+export type PaginationMeta = {
+  page: number;
+  perPage: number;
+  total: number;
+  totalPages: number;
+};
+
+export type PaginatedResponse<T = unknown> = {
+  meta: PaginationMeta;
+} & ApiResponse<T[]>;
+
+// Since we only ever fetch a single API we don't need multiple failure types,
+// so defining a global one as the default is fine. This can be changed per-app.
+export type ApiFailure = { message: string };
+
+type GenericResponse<Ok, Error> =
+  | ({
+      readonly ok: true;
+      json(): Promise<Ok | null>;
+    } & globalThis.Response)
+  | ({
+      readonly ok: false;
+      json(): Promise<Error>;
+    } & globalThis.Response);
+
+export type Response<Ok, Error> = GenericResponse<Ok, Error>;
+
+/**
+ * Typesafe version of the normal `fetch` function. It takes 2 generics:
+ * - `Ok` which defines type type of a successful request
+ * - `Error` which defines the type of a failed request (defaults to  the `ApiFailure` type)
+ *
+ * @param input The URL to fetch
+ * @param init Any fetch options, like cache, headers, body, etc.
+ */
+export declare function fetch<Ok = never, Error = ApiFailure>(
+  input: RequestInfo | URL,
+  init?: RequestInit,
+): Promise<Response<Ok, Error>>;
+
+export type WrappedApiResponse<T> = Promise<
+  | { success: true; data: T }
+  | { success: false; message: string; status?: number; details?: string[] }
+>;

package/src/types/auth.ts

@@ -0,0 +1,13 @@
+// Define an interface for the decoded JWT payload
+export type DecodedJWT = {
+  name: string;
+  email: string;
+  groupInfoIds: string[];
+  exp?: number; // Optional: JWT expiration timestamp
+  [key: string]: unknown; // Additional claims
+};
+
+export type Credentials = {
+  token: string;
+  user: DecodedJWT;
+};

package/src/types/index.ts

@@ -0,0 +1,6 @@
+// Barrel export for all types
+export * from './api';
+export * from './auth';
+export * from './navigation';
+export * from './utils';
+export * from './map';

package/src/types/map.ts

@@ -0,0 +1,26 @@
+export type PopupDirection = 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+
+export type MapConfig = {
+  center: number[];
+  zoom: number;
+};
+
+export type Layer = {
+  name: string;
+  title: string;
+};
+
+export type MapSearchResults = {
+  results: {
+    GAZETTEER_ENTRY: {
+      GEOMETRY_Y: number;
+      NAME1: string;
+    };
+  }[];
+};
+
+export type TransformedResult = {
+  lon: number;
+  lat: number;
+  address: { name: string };
+}[];

package/src/types/navigation.ts

@@ -0,0 +1,8 @@
+import type { ReactNode } from 'react';
+
+export type NavLink = {
+  label: string;
+  url: string;
+  isExternal?: boolean;
+  icon?: ReactNode;
+};

package/src/types/utils.ts

@@ -0,0 +1,13 @@
+import type { ComponentProps } from 'react';
+
+// Utility types for better developer experience
+export type PropsWithRequired<T, K extends keyof T> = T & Required<Pick<T, K>>;
+export type PropsWithOptional<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
+
+export type ExtendProps<
+  // `ComponentProps` internally constrains `Comp` to be `JSXElementConstructor<any>`,
+  // and since our type must have the same constraints to avoid errors, `any` is required here
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  Comp extends keyof React.JSX.IntrinsicElements | React.JSXElementConstructor<any>,
+  Props = object,
+> = Props & Omit<ComponentProps<Comp>, keyof Props>;

package/src/utils/auth.ts

@@ -5,7 +5,7 @@ import type { NextRequest } from 'next/server';
 
 import { COOKIE_NAME } from './constants';
 import { decodeAuthToken } from './utils';
-import type { Credentials } from '../types';
+import type { Credentials } from '../types/auth';
 
 export const getCredentials = async (source?: NextRequest | null): Promise<Credentials | null> => {
   const cookieStore = source ? source?.cookies : await cookies();

package/src/utils/http.ts

@@ -0,0 +1,143 @@
+import type { Response, ApiFailure } from '../types/api';
+
+export const MimeTypes = {
+  Json: 'application/json',
+  GeoJson: 'application/geo+json',
+  Png: 'image/png',
+  XJsonLines: 'application/x-jsonlines',
+} as const;
+
+export const Http = {
+  Ok: 200,
+  Created: 201,
+  NoContent: 204,
+  BadRequest: 400,
+  NotFound: 404,
+  NotAllowed: 405,
+  InternalServerError: 500,
+} as const;
+
+export const HttpMethod = {
+  Get: 'GET',
+  Post: 'POST',
+  Put: 'PUT',
+  Patch: 'PATCH',
+  Delete: 'DELETE',
+} as const;
+
+type NodeGlobal = {
+  process?: {
+    env?: Record<string, string | undefined>;
+  };
+};
+
+type BrowserGlobal = {
+  btoa?: (input: string) => string;
+  Buffer?: {
+    from: (input: string) => {
+      toString: (encoding: string) => string;
+    };
+  };
+};
+
+const isNodeEnvironment = (): boolean => {
+  const global = globalThis as NodeGlobal;
+
+  return typeof global.process?.env !== 'undefined';
+};
+
+const getNodeEnvVar = (key: string): string | undefined => {
+  if (!isNodeEnvironment()) {
+    return undefined;
+  }
+
+  const global = globalThis as NodeGlobal;
+
+  return global.process?.env?.[key];
+};
+
+const encodeBase64 = (input: string): string => {
+  const global = globalThis as BrowserGlobal;
+
+  // Check for Buffer (Node.js)
+  if (global.Buffer) {
+    return global.Buffer.from(input).toString('base64');
+  }
+
+  // Check for btoa (Browser)
+  if (global.btoa) {
+    return global.btoa(input);
+  }
+
+  throw new Error('Base64 encoding not available in this environment');
+};
+
+const getAuthorizationHeader = (): { Authorization: string } | Record<string, never> => {
+  const apiHasAuth = getNodeEnvVar('API_HAS_AUTH');
+  const apiUsername = getNodeEnvVar('API_USERNAME');
+  const apiPassword = getNodeEnvVar('API_PASSWORD');
+
+  if (apiHasAuth && apiUsername && apiPassword) {
+    const credentials = `${apiUsername}:${apiPassword}`;
+
+    return {
+      Authorization: `Basic ${encodeBase64(credentials)}`,
+    };
+  }
+
+  return {};
+};
+
+// common fetch wrapper to provide auth headers if necessary
+declare const fetch: <Ok = unknown, Error = ApiFailure>(
+  input: RequestInfo | URL,
+  init?: RequestInit,
+) => Promise<Response<Ok, Error>>;
+
+export const fetchWithAuth = <Ok, Error = ApiFailure>(
+  url: string,
+  options?: RequestInit,
+): Promise<Response<Ok, Error>> => {
+  const requestOptions = {
+    ...options,
+    headers: { ...options?.headers, ...getAuthorizationHeader() },
+  };
+
+  // Use your custom fetch declaration directly
+  return fetch<Ok, Error>(url, requestOptions);
+};
+
+const get = <Ok, Error = ApiFailure>(
+  url: string,
+  options?: RequestInit,
+): Promise<Response<Ok, Error>> => {
+  const requestOptions = {
+    ...options,
+    method: HttpMethod.Get,
+  };
+
+  return fetchWithAuth<Ok, Error>(url, requestOptions);
+};
+
+const post = <Ok, Error = ApiFailure>(
+  url: string,
+  body: unknown,
+  options?: RequestInit,
+): Promise<Response<Ok, Error>> => {
+  const requestOptions = {
+    ...options,
+    method: HttpMethod.Post,
+    body: JSON.stringify(body),
+    headers: {
+      'Content-Type': MimeTypes.Json,
+      ...options?.headers,
+    },
+  };
+
+  return fetchWithAuth<Ok, Error>(url, requestOptions);
+};
+
+export const FetchWrapper = {
+  get,
+  post,
+};

package/src/utils/index.ts

@@ -1,4 +1,4 @@
 export * from './utils';
 export * from './auth';
 export * from './constants';
-export * from './renderers'; // This has testing-library dependencies, so probably need to add them as peer dependencies
+export * from './http';

package/src/utils/utils.ts

@@ -1,7 +1,7 @@
 import { decode } from 'jsonwebtoken';
 import { twMerge } from 'tailwind-merge';
 
-import type { Credentials, DecodedJWT } from '../types';
+import type { Credentials, DecodedJWT } from '../types/auth';
 
 export const decodeAuthToken = (token: string): Credentials | null => {
   if (!token) {