pejay-ui 1.1.0 → 1.2.0

package/README.md

@@ -136,3 +136,8 @@ Below is the list of components you can add. Each has a copyable command block w
   ```bash
   npx pejay-ui add tanstack-query-client
   ```
+* **`react-router-client`**: Bare-bone React Router client layout, routing structure, and route guard setup.
+  ```bash
+  npx pejay-ui add react-router-client
+  ```
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pejay-ui",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "type": "module",
   "description": "react ui components",
   "bin": {
@@ -22,7 +22,6 @@
   "dependencies": {
     "@babel/core": "^7.24.0",
     "@babel/preset-typescript": "^7.24.0",
-    "@tanstack/react-query": "^5.100.14",
     "commander": "^12.0.0",
     "fs-extra": "^11.0.0",
     "inquirer": "^9.0.0"
@@ -39,6 +38,7 @@
   "homepage": "https://github.com/pejaybro/pejay-ui#readme",
   "devDependencies": {
     "@floating-ui/react": "^0.27.19",
+    "@tanstack/react-query": "^5.101.0",
     "@types/react": "^19.2.15",
     "@types/react-dom": "^19.2.3",
     "clsx": "^2.1.1",
@@ -46,6 +46,7 @@
     "lucide-react": "^1.17.0",
     "react": "^19.2.6",
     "react-dom": "^19.2.6",
+    "react-router-dom": "^7.16.0",
     "tailwind-merge": "^3.6.0",
     "tailwindcss": "^4.3.0",
     "typescript": "^6.0.3"

package/registry.json

@@ -194,5 +194,11 @@
     "category": "tanstack-query",
     "files": ["templates/scaffolds/tanstack-query"],
     "peerDependencies": ["@tanstack/react-query"]
+  },
+   "react-router-client": {
+    "name": "ReactRouterClient",
+    "category": "react-router",
+    "files": ["templates/scaffolds/react-router"],
+    "peerDependencies": ["react-router-dom"]
   }
 }

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

@@ -0,0 +1,131 @@
+import { useCallback, useMemo, useRef } from "react";
+import { useSearchParams } from "react-router-dom";
+
+export function useRouterSearch<T extends Record<string, any>>({
+  defaultParams,
+}: {
+  defaultParams: T;
+}) {
+  const [searchParams, setSearchParams] = useSearchParams();
+
+  const defaultRef = useRef(defaultParams);
+  defaultRef.current = defaultParams;
+
+  const search = useMemo(() => {
+    const result = { ...defaultRef.current };
+    const keys = Object.keys(defaultRef.current);
+
+    for (const key of keys) {
+      const fallback = defaultRef.current[key];
+      if (Array.isArray(fallback)) {
+        const val = searchParams.getAll(key);
+        if (val.length > 0) {
+          result[key as keyof T] = parseValue(val, fallback) as any;
+        }
+      } else {
+        const val = searchParams.get(key);
+        if (val !== null) {
+          result[key as keyof T] = parseValue(val, fallback) as any;
+        }
+      }
+    }
+    return result;
+  }, [searchParams]);
+
+  const setSearch = useCallback(
+    (
+      updates: Partial<Record<keyof T, any>>,
+      options?: { resetPage?: boolean; replace?: boolean }
+    ) => {
+      const next = new URLSearchParams(searchParams);
+      const keys = Object.keys(defaultRef.current);
+
+      for (const key of keys) {
+        const value = updates[key as keyof T];
+        if (value !== undefined) {
+          if (value === null || areEqual(value, defaultRef.current[key])) {
+            next.delete(key);
+          } else if (Array.isArray(value)) {
+            next.delete(key);
+            value.forEach((val) => {
+              if (val !== undefined && val !== null && val !== "") {
+                next.append(key, String(val));
+              }
+            });
+          } else {
+            next.set(key, String(value));
+          }
+        }
+      }
+      /**
+       * Reset pagination
+       * when filters/search changes
+       */
+      if (options?.resetPage && "page" in defaultRef.current) {
+        next.delete("page");
+      }
+
+      setSearchParams(next, {
+        replace: options?.replace,
+      });
+    },
+    [searchParams, setSearchParams]
+  );
+
+  return { search, setSearch };
+}
+
+function areEqual(a: any, b: any) {
+  if (Array.isArray(a) && Array.isArray(b)) {
+    if (a.length !== b.length) return false;
+    const sortedA = [...a].sort();
+    const sortedB = [...b].sort();
+    return sortedA.every((val, index) => val === sortedB[index]);
+  }
+  return a === b;
+}
+
+function parseValue(value: string | string[], fallback: any): any {
+  if (Array.isArray(fallback)) {
+    const fallbackVal = fallback[0];
+    const valArray = Array.isArray(value) ? value : [value];
+    return valArray.map((item) => parseSingleValue(item, fallbackVal));
+  }
+  const singleVal = Array.isArray(value) ? value[0] : value;
+  return parseSingleValue(singleVal, fallback);
+}
+
+function parseSingleValue(value: string, fallback: any) {
+  if (typeof fallback === "number") {
+    const parsed = Number(value);
+    return Number.isNaN(parsed) ? fallback : parsed;
+  }
+
+  /**
+   * Boolean parsing
+   */
+  if (typeof fallback === "boolean") {
+    return value === "true";
+  }
+
+  /**
+   * String fallback
+   */
+  return value;
+}
+
+/*
+# NOTE: Array parameter usage example
+
+1. Define the default parameter as an array:
+   export const DefaultSearch = {
+     color: [] as string[],
+   };
+
+2. Set values (e.g., in a component):
+   setSearch({ color: ["red", "blue"] });
+   // Resulting URL query: ?color=red&color=blue
+
+3. Read values (e.g., in a component):
+   const colors = search.color; // Returns ["red", "blue"]
+*/

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

@@ -0,0 +1,56 @@
+import { Outlet } from "react-router-dom";
+
+export function PrivateRoute() {
+  return <Outlet />;
+}
+
+/* 
+# NOTE : use this when you want to redirect user to login page if he is already logged out.
+#        Includes the premium "Redirect Back" pattern to preserve user navigation state.
+
+import { Navigate, Outlet, useLocation } from "react-router-dom";
+
+export default function PrivateRoute() {
+  const token = getLocalAuthToken();
+  const location = useLocation();
+
+  if (!token) {
+    // Passes the requested path inside search params so you can redirect back after successful login
+    return (
+      <Navigate 
+        to={`/page_auth?redirectTo=${encodeURIComponent(location.pathname + location.search)}`} 
+        replace 
+      />
+    );
+  }
+  return <Outlet />;
+}
+
+# NOTE: HOW THE LOGIN COMPONENT CONSUMES THE "redirectTo" PARAMETER
+
+### The Bookmarking Lifecycle Flow:
+1. **Bookmarked Access:** A logged-out user tries to access a bookmarked private route directly:
+   `https://your-app.com/page_two`
+2. **Redirect to Auth:** The `PrivateRoute` guard intercepts the request, captures the target pathname (`/page_two`), and redirects them to the login screen with the target appended:
+   `https://your-app.com/page_auth?redirectTo=%2Fpage_two`
+3. **Login:** The user submits their login credentials.
+4. **Target Restoration:** Upon successful authentication, the Login page checks the URL for `redirectTo` and navigates the user straight to `/page_two` instead of the generic homepage `/`.
+
+### Code Implementation Example:
+```typescript
+import { useNavigate, useSearchParams } from "react-router-dom";
+
+export default function LoginPage() {
+  const navigate = useNavigate();
+  const [searchParams] = useSearchParams();
+
+  const handleLoginSuccess = () => {
+    // 1. Read the redirectTo value (e.g., "/page_two") or default to "/"
+    const destination = searchParams.get("redirectTo") || "/";
+
+    // 2. Redirect the user back to their bookmarked page instead of the root page!
+    navigate(destination, { replace: true });
+  };
+}
+```
+*/

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

@@ -0,0 +1,21 @@
+import { Outlet } from "react-router-dom";
+
+export function PublicRoute() {
+  return <Outlet />;
+}
+
+/* 
+
+# NOTE : use this when you want to redirect user to main page if he is already logged in
+
+import { Navigate, Outlet } from "react-router-dom";
+
+export default function PublicRoute() {
+  const token = getLocalAuthToken();
+  if (token) {
+    return <Navigate to={PATH.desired_path_name} replace />;
+  }
+  return <Outlet />;
+}
+
+*/

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

@@ -0,0 +1,186 @@
+import { createBrowserRouter, RouteObject } from "react-router-dom";
+import { PATH } from "./path";
+import { PublicRoute } from "./guards/public.route";
+import { PrivateRoute } from "./guards/private.route";
+import { AuthLayout } from "./layouts/auth.layout";
+import { ErrorLayout } from "./layouts/error.layout";
+import { MainLayout } from "./layouts/main.layout";
+
+const PublicRoutes: RouteObject[] = [
+  {
+    Component: PublicRoute,
+    children: [
+      {
+        Component: AuthLayout,
+        ErrorBoundary: ErrorLayout,
+        children: [
+          {
+            path: PATH.page_auth(),
+            lazy: async () => {
+              const module = await import("../routes/page-auth");
+              return { Component: module.default };
+            },
+          },
+        ],
+      },
+    ],
+  },
+];
+
+const PrivateRoutes: RouteObject[] = [
+  {
+    Component: PrivateRoute,
+    children: [
+      {
+        Component: MainLayout,
+        ErrorBoundary: ErrorLayout,
+        children: [
+          {
+            path: PATH.page_root(),
+            ErrorBoundary: ErrorLayout,
+            lazy: async () => {
+              const module = await import("../routes/page-root");
+              return { Component: module.default };
+            },
+          },
+          {
+            path: PATH.page_one(),
+            ErrorBoundary: ErrorLayout,
+            lazy: async () => {
+              const module = await import("../routes/page-one");
+              return { Component: module.default };
+            },
+          },
+          {
+            path: PATH.page_two(),
+            ErrorBoundary: ErrorLayout,
+            lazy: async () => {
+              const module = await import("../routes/page-two");
+              return { Component: module.default };
+            },
+          },
+        ],
+      },
+    ],
+  },
+];
+
+const NotFoundRoutes: RouteObject[] = [
+  {
+    path: PATH.not_found(), // Wildcard catch-all must be at the end of the root array
+    lazy: async () => {
+      const module = await import("../routes/not-found");
+      return { Component: module.default };
+    },
+  },
+];
+
+export const router = createBrowserRouter([
+  ...PublicRoutes,
+  ...PrivateRoutes,
+  ...NotFoundRoutes,
+]);
+
+/* 
+
+currently i am using new way of using react-router version like
+Component: PrivateLayout,
+lazy: async () => ...
+
+the old way is 
+
+{
+  path: "/",
+  element: (
+    <PublicRoute>
+      <AuthLayout />
+    </PublicRoute>
+  ),
+  children: [
+    {
+      path: PATHS.LOGIN,
+      element: <Login />,
+    },
+  ],
+}
+
+
+
+| Feature              | `errorElement`                    | `ErrorBoundary`            |
+| -------------------- | --------------------------------- | -------------------------- |
+| What you pass        | React Element                     | Component Function         |
+| Syntax               | `errorElement: <ErrorPage />`     | `ErrorBoundary: ErrorPage` |
+| Requires JSX         | Yes                               | No                         |
+| Works in `.ts` file  | No (unless `React.createElement`) | Yes                        |
+| React Router version | v6.4+                             | Newer preferred API        |
+
+
+---------------------------------------------------------------------------
+
+# ANCHOR : 2 ways to show the error boundry page data 
+
+
+# NOTE : WAY-1 inside layout i.e inplace of outlet
+ {
+        path: PATH.page_two(),
+        ErrorBoundary: ErrorLayout,
+        lazy: async () => {
+          const module = await import("../routes/page-two");
+          return { Component: module.default };
+        },
+      },
+
+---------------------------------------------------------------------------
+
+      # NOTE : WAY-2 replace entire layout with error boundary
+       {
+    Component: AuthLayout,
+    ErrorBoundary: ErrorLayout,
+    children: [
+      {
+        path: PATH.page_auth(),
+        lazy: async () => {
+          const module = await import("../routes/page-auth");
+          return { Component: module.default };
+        },
+      },
+    ],
+  },
+
+---------------------------------------------------------------------------
+
+# NOTE : DYNAMIC PAGE TITLES (SEO BEST PRACTICE)
+To set browser tab titles dynamically on page transitions, create a custom hook and call it inside your page route components:
+
+```typescript
+import { useEffect } from "react";
+
+export function useDocumentTitle(title: string) {
+  useEffect(() => {
+    const original = document.title;
+    document.title = `${title} | My App`;
+    return () => {
+      document.title = original;
+    };
+  }, [title]);
+}
+
+// In routes/page-one.tsx:
+// useDocumentTitle("Analytics Page");
+```
+
+---------------------------------------------------------------------------
+
+# NOTE : ROUTE-LEVEL SUSPENSE VS. COMPONENT-LEVEL SKELETONS
+
+1. **Why we place `<Suspense>` at the very top (wrapping `<RouterProvider>`):**
+   - **Code Chunk Loading:** Because we lazy-load routes (`lazy: async () => ...`), React Router has to download the page's `.js` chunk file from the server when navigating.
+   - **Preventing UI Freezes:** If you click a link and do not have a top-level Suspense boundary, the app will freeze or flicker on the old page until the file download finishes. 
+   - **Best Practice:** Wrap the router in `<Suspense fallback={<TopBarProgressBar />} />` so the user gets instant progress feedback when clicking links.
+
+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.
+ */
+
+

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

@@ -0,0 +1,5 @@
+import { Outlet } from "react-router-dom";
+
+export function AuthLayout() {
+  return <Outlet />;
+}

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

@@ -0,0 +1,15 @@
+import { Outlet, useRouteError } from "react-router-dom";
+
+export function ErrorLayout() {
+  const error = useRouteError();
+  return (
+    <div>
+      <h1>Something went wrong!</h1>
+      <p>
+        {error instanceof Error
+          ? error.message
+          : "An unexpected error occurred"}
+      </p>
+    </div>
+  );
+}

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

@@ -0,0 +1,5 @@
+import { Outlet } from "react-router-dom";
+
+export function MainLayout() {
+  return <Outlet />;
+}

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

@@ -0,0 +1,7 @@
+export const PATH = {
+  page_root: () => "/" as const,
+  page_one: () => "/page_one" as const,
+  page_two: () => "/page_two" as const,
+  page_auth: () => "/page_auth" as const,
+  not_found: () => "*" as const,
+};

package/templates/scaffolds/react-router/routes/not-found/index.tsx

@@ -0,0 +1,3 @@
+export default function NotFound() {
+  return <div>Not Found</div>;
+}

package/templates/scaffolds/react-router/routes/page-auth/index.tsx

@@ -0,0 +1,3 @@
+export default function PageAuth() {
+  return <div>Page Auth</div>;
+}

package/templates/scaffolds/react-router/routes/page-one/index.tsx

@@ -0,0 +1,85 @@
+export default function PageOne() {
+  return <div>Page One</div>;
+}
+
+/*
+# NOTE: FRAMEWORK-LEVEL META & PRERENDERING CONFIGURATION (SEO)
+
+If you are using React Router v7 and want static HTML files compiled for SEO search crawlers, follow these steps:
+
+-------------------------------------------------------------------------------------
+
+1. ROUTE META EXPORT (Add this inside this page file):
+```typescript
+import type { MetaFunction } from "react-router-dom";
+
+export const meta: MetaFunction = () => {
+  return [
+    { title: "Page One Analytics | My App" },
+    { name: "description", content: "Analyze product sales and user logs." },
+  ];
+};
+```
+
+-------------------------------------------------------------------------------------
+
+2. PRERENDER SETTINGS (Add this in your react-router.config.ts / vite.config.ts):
+```typescript
+export default {
+  async prerender() {
+    return ["/", "/page_one", "/page_two"]; // Routes to generate as static HTML pages
+  },
+};
+```
+
+-------------------------------------------------------------------------------------
+
+3. HOW THE BUILD CHANGES (Build output comparison):
+
+OLD BUILD (Standard Single Page Application):
+- Outputs only a single empty "index.html" page.
+- Crawlers see no initial page HTML or titles when visiting "/page_one" until JS loads.
+
+NEW BUILD (Prerendered SPA):
+- Outputs directory folders containing index.html files:
+  dist/
+    ├── index.html            <- for "/"
+    ├── page_one/
+    │   └── index.html        <- for "/page_one" (contains pre-rendered metadata)
+    └── page_two/
+        └── index.html        <- for "/page_two" (contains pre-rendered metadata)
+
+-------------------------------------------------------------------------------------
+
+4. SERVER SETTINGS (VPS Deployment):
+
+For a standard VPS server (like Nginx), configure it to serve static files from your build directory. 
+Nginx will look for the folder-based index files (e.g., /page_one/index.html) first.
+
+NGINX VPS CONFIGURATION EXAMPLE (/etc/nginx/sites-available/default):
+```nginx
+server {
+    listen 80;
+    server_name your-app.com;
+
+    # Point to your build distribution directory on the VPS
+    root /var/www/your-app/dist; 
+
+    index index.html;
+
+    location / {
+        # 1. Checks if exact file exists ($uri)
+        # 2. Checks if a directory index.html exists ($uri/) -> Serves pre-rendered SEO pages!
+        # 3. Falls back to root index.html if route is handled client-side
+        try_files $uri $uri/ /index.html;
+    }
+
+    # Optional: Proxy API requests directly to your Laravel Backend
+    location /api/ {
+        proxy_pass http://127.0.0.1:8000; # Address where your Laravel backend runs
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+    }
+}
+```
+*/

package/templates/scaffolds/react-router/routes/page-one/search.page-one.ts

@@ -0,0 +1,5 @@
+export const PageOneDefaultSearchParam = {
+  param_one: "",
+  param_two: "",
+  param_three: "",
+};

package/templates/scaffolds/react-router/routes/page-root/index.tsx

@@ -0,0 +1,3 @@
+export default function PageRoot() {
+  return <div>Page Root</div>;
+}

package/templates/scaffolds/react-router/routes/page-two/index.tsx

@@ -0,0 +1,3 @@
+export default function PageTwo() {
+  return <div>Page Two</div>;
+}

package/templates/scaffolds/react-router/routes/page-two/search.page-two.ts

@@ -0,0 +1,5 @@
+export const PageTwoDefaultSearchParam = {
+  param_one: "",
+  param_two: "",
+  param_three: "",
+};

package/templates/scaffolds/tanstack-query/api-queries.ts

@@ -58,9 +58,28 @@ return <ModuleComponent data={data} />;
 }
 
 # NOTE : Wrapping
+ <ErrorBoundary fallback={<div>Failed to load Stats</div>}>
 <Suspense fallback={<FallBackComponent />}>
   <ModuleComponent />
 </Suspense>
+  </ErrorBoundary>
+
+  this is comp level error boundary in case of api fails then suspense bubbeling up will touch this first and stops 
+  in case this is not present then the router level
+  so in this way we can only show a particaular comp failed to load not entore page
+
+
+
+
+
+  Manually (Option A - useQuery):
+
+Code: if (error) return <ErrorComponent />
+Behavior: Bypasses Error Boundaries. Component-level and router-level boundaries never trigger.
+Automatically (Option B - useSuspenseQuery or useQuery with throwOnError: true):
+
+Code: Component throws the error during render.
+Behavior: The error bubbles up. It triggers the nearest Error Boundary (either your component-level boundary if you wrapped it, or falls back to the router-level boundary).
 
 ---------------------------------------------------------------------------------------------------
 

package/templates/scaffolds/tanstack-query/module/queries.ts

@@ -1,4 +1,8 @@
-import { queryOptions, infiniteQueryOptions, keepPreviousData } from "@tanstack/react-query";
+import {
+  queryOptions,
+  infiniteQueryOptions,
+  keepPreviousData,
+} from "@tanstack/react-query";
 
 import { ModuleKeys } from "./keys";
 import { ModuleMappers } from "./mappers";
@@ -15,7 +19,7 @@ export const ModuleQueries = {
         */
         return ModuleService.get_query_name_example();
       },
-      select: (raw) => {
+      select: raw => {
         /* 
         # NOTE: ModuleMappers.fetch_query_name_example() -> manipulates the data from api into desird format before returning to ui or page
         Using the 'select' property memoizes this transformation (only runs when cached data changes).
@@ -50,7 +54,7 @@ export const ModuleQueries = {
         return hasMore ? current_page + 1 : undefined;
       },
       initialPageParam: 1,
-      select: (raw) => {
+      select: raw => {
         /* 
         # NOTE: ModuleMappers.fetch_infinite_query_example() -> manipulates the data from api into desird format before returning to ui or page
         Using the 'select' property memoizes this transformation (only runs when cached data changes).
@@ -76,7 +80,7 @@ export const ModuleQueries = {
         */
         return ModuleService.get_query_with_params_example(params, signal);
       },
-      select: (raw) => {
+      select: raw => {
         // Reusing the same mapper example for consistency
         return ModuleMappers.fetch_query_name_example(raw as any);
       },
@@ -89,7 +93,7 @@ export const ModuleQueries = {
       queryFn: ({ signal }) => {
         return ModuleService.get_query_by_id_example(id!, signal);
       },
-      select: (raw) => {
+      select: raw => {
         return ModuleMappers.fetch_query_name_example(raw as any);
       },
       placeholderData: keepPreviousData,
@@ -100,13 +104,16 @@ export const ModuleQueries = {
       enabled: !!id,
     }),
 
-  fetch_query_combo_example: (id: string | null | undefined, params: Record<string, any>) =>
+  fetch_query_combo_example: (
+    id: string | null | undefined,
+    params: Record<string, any>,
+  ) =>
     queryOptions({
       queryKey: ModuleKeys.fetch_query_combo_example(id || "", params),
       queryFn: ({ signal }) => {
         return ModuleService.get_query_combo_example(id!, params, signal);
       },
-      select: (raw) => {
+      select: raw => {
         return ModuleMappers.fetch_query_name_example(raw as any);
       },
       placeholderData: keepPreviousData,
@@ -129,5 +136,21 @@ export const ModuleQueries = {
    - The `select` function is **automatically memoized** by TanStack Query.
    - It will ONLY re-run when the cached raw data changes. 
    - If the component re-renders for other reasons (e.g., local UI states, parent re-renders, or window focus checks), TanStack Query skips the mapper execution completely and returns the already memoized mapped data instantly.
-*/
 
+
+
+
+
+
+
+
+
+
+
+use this inside queries if you want to show error boundary at component level for perticular query when not using useSuspenseQuery or hook which provides suspense by default. by default it just catches the errror and shows the error in useMutation or useQuery hooks but in case of useSuspenseQuery it throws the error and bubbels up to the nearest error boundary.
+
+    throwOnError: (error) => {
+      // Throw to boundary for severe errors (like 404 Not Found or 500 Server Crashes)
+      return error.status === 404 || error.status >= 500;
+    }
+*/