pejay-ui 1.2.2 → 1.3.0

package/templates/scaffolds/axios/api/index.ts

@@ -0,0 +1,40 @@
+export * as oneAPI from "./one.api";
+/* 
+
+to call we simply do 
+
+import {oneAPI} from "@/api"
+
+oneAPI.onePost({ payload: data });
+
+oneAPI.oneGet();
+
+oneAPI.oneGetId({ id: "1" });
+
+* calling abort via signal
+const controller = new AbortController();
+oneAPI.oneGetIdParams({ id: "1", params: { search:"adam" }, signal: controller.signal, });
+
+controller.abort();
+
+* aborts request on unmount
+useEffect(() => {
+  const controller = new AbortController();
+
+  oneAPI.oneGetIdParams({
+    id: "1",
+    params: { search: "adam" },
+    signal: controller.signal,
+  });
+
+  return () => {
+    controller.abort();
+  };
+}, []);
+
+
+oneAPI.onePut({ id: "1", payload: data });
+
+oneAPI.oneDelete({ id: "1" });
+
+*/

package/templates/scaffolds/axios/api/one.api.ts

@@ -0,0 +1,94 @@
+import { ENDPOINTS } from "../endpoints";
+import { CustomAxiosRequestConfig, request } from "../request";
+
+type RequestOptions = Pick<
+  CustomAxiosRequestConfig,
+  "signal" | "skipErrorToast"
+>;
+
+export async function onePost(
+  { payload }: { payload: any },
+  options?: RequestOptions,
+) {
+  return await request({
+    url: ENDPOINTS.USER.BASE,
+    method: "POST",
+    data: payload,
+    ...options,
+  });
+}
+
+export async function onePostFile(
+  { payload }: { payload: any },
+  options?: RequestOptions,
+) {
+  return await request({
+    ...options,
+    url: ENDPOINTS.USER.BASE,
+    method: "POST",
+    data: payload,
+    headers: {
+      "Content-Type": "multipart/form-data",
+    },
+  });
+}
+
+export async function oneGet(options?: RequestOptions) {
+  return await request({
+    url: ENDPOINTS.USER.BASE,
+    method: "GET",
+    ...options,
+  });
+}
+
+export async function oneGetId(
+  { id }: { id: string },
+  options?: RequestOptions,
+) {
+  return await request({
+    url: ENDPOINTS.USER.BY_ID(id),
+    method: "GET",
+    ...options,
+  });
+}
+
+export async function oneGetIdParams(
+  {
+    id,
+    params,
+  }: {
+    id: string;
+    params: any;
+  },
+  options?: RequestOptions,
+) {
+  return await request({
+    url: ENDPOINTS.USER.BY_ID(id),
+    method: "GET",
+    params,
+    ...options,
+  });
+}
+
+export async function onePut(
+  { id, payload }: { id: string; payload: any },
+  options?: RequestOptions,
+) {
+  return await request({
+    url: ENDPOINTS.USER.BY_ID(id),
+    method: "PUT",
+    data: payload,
+    ...options,
+  });
+}
+
+export async function oneDelete(
+  { id }: { id: string },
+  options?: RequestOptions,
+) {
+  return await request({
+    url: ENDPOINTS.USER.BY_ID(id),
+    method: "DELETE",
+    ...options,
+  });
+}

package/templates/scaffolds/axios/endpoints.ts

@@ -0,0 +1,9 @@
+const createResourceEndpoints = (base: string) => ({
+  BASE: base,
+  BY_ID: (id: string) => `${base}/${id}`,
+});
+
+export const ENDPOINTS = {
+  USER: createResourceEndpoints("/user"),
+  CATEGORY_2: createResourceEndpoints("/category-2"),
+};

package/templates/scaffolds/axios/index.ts

@@ -0,0 +1,26 @@
+import axios from "axios";
+
+export const axiosInstance = axios.create({
+  baseURL: "http://localhost:5001",
+  timeout: 5000,
+  headers: {
+    "Content-Type": "application/json",
+  },
+});
+
+/*
+const api = axios.create({ timeout: 5000 });
+This specific request uses a 30-second timeout instead
+await api.get("/slow-endpoint", { timeout: 30000 });
+*/
+
+/* 
+TO integrate
+1. Generic response typing (HIGH PRIORITY)
+2. Error normalization utility
+3. Network error utility
+4. File upload helpers
+5. File download helpers
+6. Refresh-token queue
+7. Monitoring hooks
+*/

package/templates/scaffolds/axios/interceptors.ts

@@ -0,0 +1,103 @@
+import { AxiosHeaders } from "axios";
+
+import { axiosInstance } from ".";
+
+let requestInterceptorId: number | null = null;
+let responseInterceptorId: number | null = null;
+
+export const setupInterceptors = ({
+  getAccessToken,
+  onUnauthorized,
+}: {
+  getAccessToken: () => string;
+  onUnauthorized: () => void;
+}) => {
+  if (requestInterceptorId !== null) {
+    axiosInstance.interceptors.request.eject(requestInterceptorId);
+  }
+
+  if (responseInterceptorId !== null) {
+    axiosInstance.interceptors.response.eject(responseInterceptorId);
+  }
+
+  requestInterceptorId = axiosInstance.interceptors.request.use(
+    (config) => {
+      const token = getAccessToken();
+
+      if (token) {
+        config.headers = AxiosHeaders.from(config.headers);
+        config.headers.set("Authorization", `Bearer ${token}`);
+      }
+
+      return config;
+    },
+    (error) => Promise.reject(error),
+  );
+
+  responseInterceptorId = axiosInstance.interceptors.response.use(
+    (response) => response,
+    (error) => {
+      if (error?.response?.status === 401) {
+        onUnauthorized?.();
+      }
+
+      /*
+       const skipToast = error?.config?.skipErrorToast;
+         if (!skipToast) {
+                const message =
+                      error?.response?.data?.message ||
+                     error?.message || "Something went wrong";
+                toast.error(message);
+          }
+
+
+          another method Handle only generic errors globally:
+          (error) => {
+  const status = error?.response?.status;
+
+  if (status >= 500) {
+    toast.error("Server error");
+  }
+
+  return Promise.reject(error);
+}
+  And let components handle:
+  400 Validation Error
+422 Form Error
+409 Duplicate Record
+because those errors are usually specific to the screen.
+
+A practical setup is:
+Interceptor:
+  401 → logout / redirect
+  500 → generic toast
+
+Component:
+  400 → form validation
+  404 → custom UI
+  409 → business logic errors
+
+  This avoids flooding users with duplicate or overly generic error toasts while still preventing the UI from crashing.
+      */
+
+      return Promise.reject(error);
+    },
+  );
+};
+
+/*
+Call `setupInterceptors(...)` once from your app entry file or root provider,
+before any API request runs.
+
+Call setupInterceptors(...) once in your app bootstrap, like App.tsx, main.tsx, or a root provider. That is the real integration step.
+
+Example:
+import { setupInterceptors } from "./templates/axios/interceptors";
+
+setupInterceptors({
+  getAccessToken: () => localStorage.getItem("token") ?? "",
+  onUnauthorized: () => {
+    // logout / redirect here
+  },
+});
+*/

package/templates/scaffolds/axios/request.ts

@@ -0,0 +1,32 @@
+import { AxiosRequestConfig, AxiosResponse } from "axios";
+
+import { axiosInstance } from ".";
+
+export interface CustomAxiosRequestConfig extends AxiosRequestConfig {
+  skipErrorToast?: boolean;
+}
+
+export const request = async ({
+  url,
+  method = "GET",
+  data,
+  params,
+  headers,
+  signal,
+  skipErrorToast,
+  ...config
+}: CustomAxiosRequestConfig): Promise<AxiosResponse> => {
+  const axiosConfig: CustomAxiosRequestConfig = {
+    ...config,
+    url,
+    method,
+    data,
+    params,
+    headers,
+    signal,
+    skipErrorToast,
+  };
+
+  const response = await axiosInstance(axiosConfig as AxiosRequestConfig);
+  return response;
+};

package/templates/scaffolds/react-router/hook/useRouterSearch.ts

@@ -8,6 +8,10 @@ export function useRouterSearch<T extends Record<string, any>>({
 }) {
   const [searchParams, setSearchParams] = useSearchParams();
 
+  /*
+   * Keep defaults in a ref so setSearch always reads the latest defaults without
+   * forcing callbacks to be recreated. Prefer passing a stable default object.
+   */
   const defaultRef = useRef(defaultParams);
   defaultRef.current = defaultParams;
 
@@ -18,6 +22,7 @@ export function useRouterSearch<T extends Record<string, any>>({
     for (const key of keys) {
       const fallback = defaultRef.current[key];
       if (Array.isArray(fallback)) {
+        // Repeated URL keys are parsed back into arrays, e.g. ?color=red&color=blue.
         const val = searchParams.getAll(key);
         if (val.length > 0) {
           result[key as keyof T] = parseValue(val, fallback) as any;
@@ -43,9 +48,11 @@ export function useRouterSearch<T extends Record<string, any>>({
       for (const key of keys) {
         const value = updates[key as keyof T];
         if (value !== undefined) {
+          // null or the default value removes the key, keeping URLs shareable and minimal.
           if (value === null || areEqual(value, defaultRef.current[key])) {
             next.delete(key);
           } else if (Array.isArray(value)) {
+            // Delete first so array updates replace previous repeated keys instead of appending to them.
             next.delete(key);
             value.forEach((val) => {
               if (val !== undefined && val !== null && val !== "") {
@@ -78,6 +85,7 @@ export function useRouterSearch<T extends Record<string, any>>({
 function areEqual(a: any, b: any) {
   if (Array.isArray(a) && Array.isArray(b)) {
     if (a.length !== b.length) return false;
+    // Treat array query params as order-insensitive filter sets.
     const sortedA = [...a].sort();
     const sortedB = [...b].sort();
     return sortedA.every((val, index) => val === sortedB[index]);

package/templates/scaffolds/react-router/router/guards/private.route.tsx

@@ -46,6 +46,7 @@ export default function LoginPage() {
 
   const handleLoginSuccess = () => {
     // 1. Read the redirectTo value (e.g., "/page_two") or default to "/"
+    //    In production, validate this stays an internal path before navigating.
     const destination = searchParams.get("redirectTo") || "/";
 
     // 2. Redirect the user back to their bookmarked page instead of the root page!

package/templates/scaffolds/react-router/router/index.ts

@@ -8,6 +8,10 @@ import { MainLayout } from "./layouts/main.layout";
 
 const PublicRoutes: RouteObject[] = [
   {
+    /*
+    # NOTE: Guard routes without a path run before their children.
+    This keeps auth decisions centralized while the nested layout controls shared UI.
+    */
     Component: PublicRoute,
     children: [
       {
@@ -29,6 +33,10 @@ const PublicRoutes: RouteObject[] = [
 
 const PrivateRoutes: RouteObject[] = [
   {
+    /*
+    # NOTE: PrivateRoute can block or redirect every route below it.
+    Any child route added here automatically inherits the same auth requirement.
+    */
     Component: PrivateRoute,
     children: [
       {
@@ -78,6 +86,7 @@ const NotFoundRoutes: RouteObject[] = [
 export const router = createBrowserRouter([
   ...PublicRoutes,
   ...PrivateRoutes,
+  // Keep the wildcard route last so specific public/private routes get matched first.
   ...NotFoundRoutes,
 ]);
 
@@ -181,6 +190,23 @@ export function useDocumentTitle(title: string) {
 2. **Why we use Component-level skeletons:**
    - **Data Loading:** Once the page code is downloaded and mounted, your API data fetching starts.
    - **Interactive UI:** This is where you render custom skeleton loaders inside your page components while waiting for TanStack Query data, offering a premium and localized loading layout.
+
+   -------------------------------------------------------------------------------------
+
+   {
+  path: PATH.loads(),
+  handle: {
+    title: PAGE_TITLE.loads,
+  },
+  Component: LoadsPage,
+}
+
+import { useMatches } from "react-router";
+
+const matches = useMatches();
+
+const currentTitle =
+  matches[matches.length - 1]?.handle?.title ?? "";
  */
 
 

package/templates/scaffolds/react-router/router/layouts/error.layout.tsx

@@ -1,4 +1,4 @@
-import { Outlet, useRouteError } from "react-router-dom";
+import { useRouteError } from "react-router-dom";
 
 export function ErrorLayout() {
   const error = useRouteError();

package/templates/scaffolds/redux-store/reducers.ts

@@ -0,0 +1,30 @@
+import { combineReducers } from "@reduxjs/toolkit";
+import oneReducer from "./slices/one.slice";
+import twoReducer from "./slices/two.slice";
+import { persistReducer } from "redux-persist";
+import storageLocal from "redux-persist/lib/storage";
+/* import storageSession from "redux-persist/lib/storage/session"; */
+
+/*
+
+# NOTE : combineReducers is used to combine multiple reducers into a single reducer
+*/
+
+/* this is per slice config you have to define multiple if you have multi-slice persisted reducers */
+const twoConfig = {
+  key: "two",
+  storage: storageLocal,
+  whitelist: [],
+  blacklist: [],
+};
+const persistedReducers = {
+  two: persistReducer(twoConfig, twoReducer),
+};
+
+const reducres = { one: oneReducer };
+export const rootReducer = combineReducers({
+  ...reducres,
+  ...persistedReducers,
+});
+export type RootReducerState = ReturnType<typeof rootReducer>;
+export default rootReducer;

package/templates/scaffolds/redux-store/selector/one.selector.ts

@@ -0,0 +1,43 @@
+import { createSelector } from "@reduxjs/toolkit";
+import { RootState } from "../index";
+
+export const selectOneSlice = (state: RootState) => state.one;
+export const oneSelector = createSelector([selectOneSlice], (state) => {
+  if (state.oneData) {
+    return state.oneData;
+  } else {
+    return null;
+  }
+});
+
+/*
+
+# NOTE : Its primary job is:
+1. Memoize expensive calculations
+2. Return stable references (same array/object if inputs didn't change)
+3. Prevent unnecessary recalculations and re-renders
+
+
+now after this setp of selctor 
+we can handover all the states and memoised data to hook which can be called inside any number of component 
+it will save our time and code from repeating the code again and again 
+
+# NOTE : example
+
+// hooks/useOne.ts
+import { useSelector } from "react-redux";
+import { selectOneSlice } from "../store/selector/one.selector";
+
+
+export const useOne = () => {
+  const one = useSelector(selectOneSlice);
+  const { isLoading, isFetching, isError } = useSelector((state) => state.one);
+   any additional manipulation specific to component can be done here
+  return { one, isLoading, isFetching, isError };
+};
+
+ usage in any component
+import { useOne } from "../hooks/useOne";
+const { one, isLoading, isFetching, isError } = useOne();
+
+*/

package/templates/scaffolds/redux-store/selector/two.selector.ts

@@ -0,0 +1,11 @@
+import { createSelector } from "@reduxjs/toolkit";
+import { RootState } from "../index";
+
+export const selectTwoSlice = (state: RootState) => state.two;
+export const twoSelector = createSelector([selectTwoSlice], (state) => {
+  if (state.twoData) {
+    return state.twoData;
+  } else {
+    return null;
+  }
+});