rn-custom-ui 1.0.0

package/src/customFunctions/string.ts

@@ -0,0 +1,119 @@
+export const capitalizeFirst = (value: string): string => {
+  if (!value) {
+    return '';
+  }
+
+  return value.charAt(0).toUpperCase() + value.slice(1);
+};
+
+export const getLocalizedSplitText = (
+  text: string | undefined,
+  language: string,
+  options?: { englishCode?: string; delimiter?: string }
+): string => {
+  if (typeof text !== 'string' || !text) {
+    return '';
+  }
+
+  const delimiter = options?.delimiter ?? '||';
+  const englishCode = options?.englishCode ?? 'en';
+  const parts = text.split(delimiter);
+
+  if (language.startsWith('fr')) {
+    return parts[1]?.trim() ?? parts[0]?.trim() ?? '';
+  }
+
+  if (language.startsWith(englishCode)) {
+    return parts[0]?.trim() ?? '';
+  }
+
+  return parts[0]?.trim() ?? '';
+};
+
+export const removeDuplicates = <T>(items: T[]): T[] =>
+  Array.from(new Set(items));
+
+export const removeDuplicateStrings = (items: string[]): string[] =>
+  removeDuplicates(items);
+
+export const findItemByProperty = <T extends Record<string, unknown>>(
+  items: T[] | null | undefined,
+  property: keyof T,
+  value: unknown
+): T | undefined => {
+  if (!items?.length) {
+    return undefined;
+  }
+
+  return items.find((item) => item[property] === value);
+};
+
+export const truncate = (
+  value: string,
+  maxLength: number,
+  suffix = '...'
+): string => {
+  if (!value || value.length <= maxLength) {
+    return value;
+  }
+
+  return `${value.slice(0, Math.max(0, maxLength - suffix.length))}${suffix}`;
+};
+
+export const capitalizeWords = (value: string): string =>
+  value
+    .trim()
+    .split(/\s+/)
+    .filter(Boolean)
+    .map((word) => capitalizeFirst(word.toLowerCase()))
+    .join(' ');
+
+export const slugify = (value: string): string =>
+  value
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9\s-]/g, '')
+    .replace(/\s+/g, '-')
+    .replace(/-+/g, '-');
+
+export const maskString = (
+  value: string,
+  options: {
+    visibleStart?: number;
+    visibleEnd?: number;
+    maskChar?: string;
+  } = {}
+): string => {
+  const { visibleStart = 0, visibleEnd = 4, maskChar = '*' } = options;
+
+  if (!value) {
+    return '';
+  }
+
+  if (value.length <= visibleStart + visibleEnd) {
+    return maskChar.repeat(value.length);
+  }
+
+  const start = value.slice(0, visibleStart);
+  const end = value.slice(-visibleEnd);
+  const masked = maskChar.repeat(value.length - visibleStart - visibleEnd);
+
+  return `${start}${masked}${end}`;
+};
+
+export const normalizeWhitespace = (value: string): string =>
+  value.trim().replace(/\s+/g, ' ');
+
+export const initialsFromName = (fullName: string, maxInitials = 2): string => {
+  const parts = normalizeWhitespace(fullName).split(' ').filter(Boolean);
+
+  return parts
+    .slice(0, maxInitials)
+    .map((part) => part.charAt(0).toUpperCase())
+    .join('');
+};
+
+export const camelToTitle = (value: string): string =>
+  capitalizeWords(
+    value.replace(/([a-z])([A-Z])/g, '$1 $2').replace(/[-_]/g, ' ')
+  );

package/src/customFunctions/types.ts

@@ -0,0 +1,25 @@
+export type CurrencyLocale = 'en-US' | 'en-CA' | 'fr-CA' | 'fr-FR' | string;
+
+export type FormatCurrencyOptions = {
+  locale?: CurrencyLocale;
+  currency?: string;
+  isDiscount?: boolean;
+  minimumFractionDigits?: number;
+  maximumFractionDigits?: number;
+};
+
+export type FormatNumberOptions = {
+  locale?: string;
+  minimumFractionDigits?: number;
+  maximumFractionDigits?: number;
+};
+
+export type LocalizedDateTimeOptions = {
+  englishLocale?: string;
+  frenchLocale?: string;
+};
+
+export type LoggerPayload = {
+  msg?: string;
+  data?: unknown;
+};

package/src/customFunctions/validation.ts

@@ -0,0 +1,49 @@
+const EMAIL_REGEX = /^[^\s@]+@[^\s@]+\.[^\s@]{2,}$/;
+const URL_REGEX =
+  /^(https?:\/\/)?([\w-]+\.)+[\w-]{2,}(\/[\w\-._~:/?#[\]@!$&'()*+,;=]*)?$/i;
+const PHONE_REGEX = /^\+?[\d\s().-]{7,20}$/;
+const NUMERIC_REGEX = /^-?\d+(\.\d+)?$/;
+
+export const isValidEmail = (email: string): boolean => EMAIL_REGEX.test(email);
+
+export const isValidUrl = (value: string): boolean =>
+  URL_REGEX.test(value.trim());
+
+export const isValidPhone = (value: string): boolean =>
+  PHONE_REGEX.test(value.trim());
+
+export const isNumeric = (value: string | number): boolean =>
+  NUMERIC_REGEX.test(String(value).trim());
+
+export const isStrongPassword = (
+  password: string,
+  options: {
+    minLength?: number;
+    requireNumber?: boolean;
+    requireLetter?: boolean;
+  } = {}
+): boolean => {
+  const { minLength = 8, requireNumber = true, requireLetter = true } = options;
+
+  if (password.length < minLength) {
+    return false;
+  }
+
+  if (requireNumber && !/\d/.test(password)) {
+    return false;
+  }
+
+  if (requireLetter && !/[a-zA-Z]/.test(password)) {
+    return false;
+  }
+
+  return true;
+};
+
+export const encodePlusInEmail = (email: string): string => {
+  if (!email.includes('+')) {
+    return email;
+  }
+
+  return email.replace(/\+/g, '%2B');
+};

package/src/customHooks/errors.ts

@@ -0,0 +1,87 @@
+import type { ApiErrorLike } from './types';
+
+export class ApiError extends Error implements ApiErrorLike {
+  status?: number;
+  code?: string;
+  details?: unknown;
+
+  constructor(
+    message: string,
+    options: {
+      status?: number;
+      code?: string;
+      details?: unknown;
+      cause?: unknown;
+    } = {}
+  ) {
+    super(message, options.cause ? { cause: options.cause } : undefined);
+    this.name = 'ApiError';
+    this.status = options.status;
+    this.code = options.code;
+    this.details = options.details;
+  }
+}
+
+export const isApiError = (error: unknown): error is ApiError =>
+  error instanceof ApiError;
+
+export const toApiError = (error: unknown): ApiError => {
+  if (isApiError(error)) {
+    return error;
+  }
+
+  if (error instanceof Error) {
+    const maybeStatus = (error as Error & { status?: number }).status;
+    const maybeCode = (error as Error & { code?: string }).code;
+    const maybeDetails = (error as Error & { details?: unknown }).details;
+
+    return new ApiError(error.message, {
+      status: maybeStatus,
+      code: maybeCode,
+      details: maybeDetails ?? error,
+      cause: error,
+    });
+  }
+
+  if (typeof error === 'string') {
+    return new ApiError(error);
+  }
+
+  if (error && typeof error === 'object') {
+    const record = error as Record<string, unknown>;
+    const message = String(
+      record.message ?? record.error ?? record.statusText ?? 'Unknown error'
+    );
+
+    return new ApiError(message, {
+      status: typeof record.status === 'number' ? record.status : undefined,
+      code: typeof record.code === 'string' ? record.code : undefined,
+      details: error,
+    });
+  }
+
+  return new ApiError('Unknown error', { details: error });
+};
+
+export const getApiErrorMessage = (
+  error: unknown,
+  fallback = 'Something went wrong'
+): string => {
+  if (!error) {
+    return fallback;
+  }
+
+  if (typeof error === 'string') {
+    return error;
+  }
+
+  if (error instanceof Error) {
+    return error.message || fallback;
+  }
+
+  if (typeof error === 'object' && error !== null && 'message' in error) {
+    return String((error as { message?: unknown }).message ?? fallback);
+  }
+
+  return fallback;
+};

package/src/customHooks/fetchJson.ts

@@ -0,0 +1,49 @@
+import { ApiError } from './errors';
+
+export type FetchJsonOptions = RequestInit & {
+  parseJson?: boolean;
+};
+
+export const fetchJson = async <TResponse>(
+  input: RequestInfo | URL,
+  options: FetchJsonOptions = {}
+): Promise<TResponse> => {
+  const { parseJson = true, headers, ...init } = options;
+
+  const response = await fetch(input, {
+    ...init,
+    headers: {
+      'Accept': 'application/json',
+      'Content-Type': 'application/json',
+      ...headers,
+    },
+  });
+
+  const rawText = await response.text();
+  let payload: unknown = rawText;
+
+  if (parseJson && rawText) {
+    try {
+      payload = JSON.parse(rawText);
+    } catch {
+      payload = rawText;
+    }
+  }
+
+  if (!response.ok) {
+    const message =
+      typeof payload === 'object' &&
+      payload !== null &&
+      'message' in payload &&
+      typeof (payload as { message?: unknown }).message === 'string'
+        ? (payload as { message: string }).message
+        : response.statusText || 'Request failed';
+
+    throw new ApiError(message, {
+      status: response.status,
+      details: payload,
+    });
+  }
+
+  return payload as TResponse;
+};

package/src/customHooks/index.ts

@@ -0,0 +1,20 @@
+export { ApiError, getApiErrorMessage, isApiError, toApiError } from './errors';
+export { fetchJson, type FetchJsonOptions } from './fetchJson';
+export { useApi } from './useApi';
+export { useLazyApi } from './useLazyApi';
+export { useMutation } from './useMutation';
+export { usePaginatedApi } from './usePaginatedApi';
+export { usePollingApi } from './usePollingApi';
+export type {
+  ApiErrorLike,
+  ApiFetcher,
+  ApiStatus,
+  ApiStatusFlags,
+  PaginatedFetcher,
+  PaginatedResponse,
+  UseApiOptions,
+  UseLazyApiOptions,
+  UseMutationOptions,
+  UsePaginatedApiOptions,
+  UsePollingApiOptions,
+} from './types';

package/src/customHooks/internal.ts

@@ -0,0 +1,67 @@
+import { useEffect, useRef } from 'react';
+
+import { toApiError } from './errors';
+import type { ApiStatus, ApiStatusFlags } from './types';
+
+export const useDependencyKey = (deps: ReadonlyArray<unknown>) =>
+  JSON.stringify(deps);
+
+export const getStatusFlags = (status: ApiStatus): ApiStatusFlags => ({
+  status,
+  isIdle: status === 'idle',
+  isLoading: status === 'loading',
+  isSuccess: status === 'success',
+  isError: status === 'error',
+});
+
+export const useIsMounted = () => {
+  const isMountedRef = useRef(true);
+
+  useEffect(() => {
+    isMountedRef.current = true;
+
+    return () => {
+      isMountedRef.current = false;
+    };
+  }, []);
+
+  return isMountedRef;
+};
+
+export const useAbortControllerRef = () => {
+  const abortRef = useRef<AbortController | null>(null);
+
+  const abort = () => {
+    abortRef.current?.abort();
+    abortRef.current = null;
+  };
+
+  const create = () => {
+    abort();
+    const controller = new AbortController();
+    abortRef.current = controller;
+    return controller;
+  };
+
+  useEffect(() => abort, []);
+
+  return { abortRef, abort, create };
+};
+
+export const normalizeApiError = <TError>(error: unknown): TError =>
+  toApiError(error) as TError;
+
+export const isAbortError = (error: unknown) => {
+  if (
+    typeof DOMException !== 'undefined' &&
+    error instanceof DOMException &&
+    error.name === 'AbortError'
+  ) {
+    return true;
+  }
+
+  return (
+    error instanceof Error &&
+    (error.name === 'AbortError' || error.message === 'Aborted')
+  );
+};

package/src/customHooks/types.ts

@@ -0,0 +1,71 @@
+export type ApiStatus = 'idle' | 'loading' | 'success' | 'error';
+
+export type ApiStatusFlags = {
+  status: ApiStatus;
+  isIdle: boolean;
+  isLoading: boolean;
+  isSuccess: boolean;
+  isError: boolean;
+};
+
+export type ApiFetcher<TData> = (signal?: AbortSignal) => Promise<TData>;
+
+export type ApiErrorLike = {
+  message: string;
+  status?: number;
+  code?: string;
+  details?: unknown;
+};
+
+export type UseApiOptions<TData, TError = ApiErrorLike> = {
+  enabled?: boolean;
+  initialData?: TData | null;
+  deps?: ReadonlyArray<unknown>;
+  keepPreviousData?: boolean;
+  onSuccess?: (data: TData) => void;
+  onError?: (error: TError) => void;
+  onSettled?: (data: TData | null, error: TError | null) => void;
+};
+
+export type UseLazyApiOptions<TData, TError = ApiErrorLike> = Omit<
+  UseApiOptions<TData, TError>,
+  'enabled'
+>;
+
+export type UseMutationOptions<TData, TVariables, TError = ApiErrorLike> = {
+  onSuccess?: (data: TData, variables: TVariables) => void;
+  onError?: (error: TError, variables: TVariables) => void;
+  onSettled?: (
+    data: TData | null,
+    error: TError | null,
+    variables: TVariables
+  ) => void;
+};
+
+export type PaginatedResponse<TItem> = {
+  items: TItem[];
+  hasMore: boolean;
+  total?: number;
+};
+
+export type PaginatedFetcher<TItem> = (
+  page: number,
+  signal?: AbortSignal
+) => Promise<PaginatedResponse<TItem>>;
+
+export type UsePaginatedApiOptions<TItem, TError = ApiErrorLike> = {
+  enabled?: boolean;
+  initialPage?: number;
+  deps?: ReadonlyArray<unknown>;
+  onSuccess?: (response: PaginatedResponse<TItem>, page: number) => void;
+  onError?: (error: TError, page: number) => void;
+};
+
+export type UsePollingApiOptions<TData, TError = ApiErrorLike> = UseApiOptions<
+  TData,
+  TError
+> & {
+  intervalMs: number;
+  pollWhenHidden?: boolean;
+  pauseOnError?: boolean;
+};

package/src/customHooks/useApi.ts

@@ -0,0 +1,107 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+import {
+  getStatusFlags,
+  isAbortError,
+  normalizeApiError,
+  useAbortControllerRef,
+  useDependencyKey,
+  useIsMounted,
+} from './internal';
+import type { ApiFetcher, ApiStatus, UseApiOptions } from './types';
+
+export const useApi = <TData, TError = unknown>(
+  fetcher: ApiFetcher<TData>,
+  options: UseApiOptions<TData, TError> = {}
+) => {
+  const {
+    enabled = true,
+    initialData = null,
+    deps = [],
+    keepPreviousData = false,
+    onSuccess,
+    onError,
+    onSettled,
+  } = options;
+
+  const [data, setData] = useState<TData | null>(initialData);
+  const [error, setError] = useState<TError | null>(null);
+  const [status, setStatus] = useState<ApiStatus>(enabled ? 'loading' : 'idle');
+
+  const fetcherRef = useRef(fetcher);
+  const callbacksRef = useRef({ onSuccess, onError, onSettled });
+  const isMountedRef = useIsMounted();
+  const { abort, create } = useAbortControllerRef();
+  const depsKey = useDependencyKey(deps);
+
+  fetcherRef.current = fetcher;
+  callbacksRef.current = { onSuccess, onError, onSettled };
+
+  const execute = useCallback(async () => {
+    const controller = create();
+
+    setStatus('loading');
+    setError(null);
+
+    if (!keepPreviousData) {
+      setData(initialData);
+    }
+
+    try {
+      const result = await fetcherRef.current(controller.signal);
+
+      if (controller.signal.aborted || !isMountedRef.current) {
+        return result;
+      }
+
+      setData(result);
+      setStatus('success');
+      callbacksRef.current.onSuccess?.(result);
+      callbacksRef.current.onSettled?.(result, null);
+      return result;
+    } catch (unknownError) {
+      if (isAbortError(unknownError)) {
+        return null;
+      }
+
+      const parsedError = normalizeApiError<TError>(unknownError);
+
+      if (!isMountedRef.current) {
+        throw parsedError;
+      }
+
+      setError(parsedError);
+      setStatus('error');
+      callbacksRef.current.onError?.(parsedError);
+      callbacksRef.current.onSettled?.(null, parsedError);
+      throw parsedError;
+    }
+  }, [create, initialData, isMountedRef, keepPreviousData]);
+
+  const refetch = useCallback(async () => execute(), [execute]);
+
+  const reset = useCallback(() => {
+    abort();
+    setData(initialData);
+    setError(null);
+    setStatus('idle');
+  }, [abort, initialData]);
+
+  useEffect(() => {
+    if (!enabled) {
+      abort();
+      setStatus('idle');
+      return;
+    }
+
+    execute().catch(() => undefined);
+  }, [abort, depsKey, enabled, execute]);
+
+  return {
+    data,
+    error,
+    ...getStatusFlags(status),
+    refetch,
+    reset,
+  };
+};

package/src/customHooks/useLazyApi.ts

@@ -0,0 +1,92 @@
+import { useCallback, useRef, useState } from 'react';
+
+import {
+  getStatusFlags,
+  isAbortError,
+  normalizeApiError,
+  useAbortControllerRef,
+  useIsMounted,
+} from './internal';
+import type { ApiFetcher, ApiStatus, UseLazyApiOptions } from './types';
+
+export const useLazyApi = <TData, TError = unknown>(
+  fetcher: ApiFetcher<TData>,
+  options: UseLazyApiOptions<TData, TError> = {}
+) => {
+  const {
+    initialData = null,
+    keepPreviousData = false,
+    onSuccess,
+    onError,
+    onSettled,
+  } = options;
+
+  const [data, setData] = useState<TData | null>(initialData);
+  const [error, setError] = useState<TError | null>(null);
+  const [status, setStatus] = useState<ApiStatus>('idle');
+
+  const fetcherRef = useRef(fetcher);
+  const callbacksRef = useRef({ onSuccess, onError, onSettled });
+  const isMountedRef = useIsMounted();
+  const { abort, create } = useAbortControllerRef();
+
+  fetcherRef.current = fetcher;
+  callbacksRef.current = { onSuccess, onError, onSettled };
+
+  const execute = useCallback(async () => {
+    const controller = create();
+
+    setStatus('loading');
+    setError(null);
+
+    if (!keepPreviousData) {
+      setData(initialData);
+    }
+
+    try {
+      const result = await fetcherRef.current(controller.signal);
+
+      if (controller.signal.aborted || !isMountedRef.current) {
+        return result;
+      }
+
+      setData(result);
+      setStatus('success');
+      callbacksRef.current.onSuccess?.(result);
+      callbacksRef.current.onSettled?.(result, null);
+      return result;
+    } catch (unknownError) {
+      if (isAbortError(unknownError)) {
+        return null;
+      }
+
+      const parsedError = normalizeApiError<TError>(unknownError);
+
+      if (!isMountedRef.current) {
+        throw parsedError;
+      }
+
+      setError(parsedError);
+      setStatus('error');
+      callbacksRef.current.onError?.(parsedError);
+      callbacksRef.current.onSettled?.(null, parsedError);
+      throw parsedError;
+    }
+  }, [create, initialData, isMountedRef, keepPreviousData]);
+
+  const reset = useCallback(() => {
+    abort();
+    setData(initialData);
+    setError(null);
+    setStatus('idle');
+  }, [abort, initialData]);
+
+  return {
+    data,
+    error,
+    ...getStatusFlags(status),
+    execute,
+    refetch: execute,
+    reset,
+  };
+};