pejay-ui 1.2.2 → 1.3.0

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

@@ -1,15 +1,15 @@
-/* 
-# NOTE : you can change *_name_example to your own query name 
-# NOTE : you can change raw to your own data after manipulation 
-*/
-
-export const ModuleMappers = {
-  fetch_query_name_example(raw: any) {
-    const data = raw || "manipulate your data here and then return it";
-    return data;
-  },
-  fetch_infinite_query_example(raw: any) {
-    const data = raw || [];
-    return data;
-  },
-};
+/* 
+# NOTE : you can change *_name_example to your own query name 
+# NOTE : you can change raw to your own data after manipulation 
+*/
+
+export const ModuleMappers = {
+  fetch_query_name_example(raw: any) {
+    const data = raw || "manipulate your data here and then return it";
+    return data;
+  },
+  fetch_infinite_query_example(raw: any) {
+    const data = raw || [];
+    return data;
+  },
+};

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

@@ -1,55 +1,59 @@
-import { mutationOptions, type QueryClient } from "@tanstack/react-query";
-import { ModuleKeys } from "./keys";
-import { ModuleService } from "./services";
-
-export const ModuleMutations = {
-  create_query_name_example: (queryClient: QueryClient) =>
-    mutationOptions({
-      mutationFn: (newItem: any) =>
-        ModuleService.post_query_name_example(newItem),
-      onMutate: async (newItem: any) => {
-        /* 
-        # OPTIMISTIC UPDATE TECHNIQUE:
-        1. Cancel outgoing refetches so they don't overwrite our optimistic update.
-        2. Snapshot the current cache value.
-        3. Optimistically insert the new item into the cache.
-        4. Return context containing the previous value for error rollbacks.
-        */
-        await queryClient.cancelQueries({ queryKey: ModuleKeys.fetch_query_name_example() });
-
-        const previousItems = queryClient.getQueryData(ModuleKeys.fetch_query_name_example());
-
-        queryClient.setQueryData(ModuleKeys.fetch_query_name_example(), (old: any) => {
-          return old ? [...old, newItem] : [newItem];
-        });
-
-        return { previousItems };
-      },
-      onSuccess: async () => {
-        /* 
-        # NOTE: In case of mutations, invalidate query keys to refresh with fresh server data.
-        */
-        await queryClient.invalidateQueries({
-          queryKey: ModuleKeys.fetch_query_name_example(),
-        });
-      },
-      onError: (error, newItem, context: any) => {
-        /* 
-        # ROLLBACK ON FAILURE:
-        If the mutation fails, rollback the cache to our snapshotted state.
-        */
-        if (context?.previousItems) {
-          queryClient.setQueryData(
-            ModuleKeys.fetch_query_name_example(),
-            context.previousItems
-          );
-        }
-      },
-      onSettled: async () => {
-        // Always refetch after error or success to keep server in sync
-        await queryClient.invalidateQueries({
-          queryKey: ModuleKeys.fetch_query_name_example(),
-        });
-      },
-    }),
-};
+import { mutationOptions, type QueryClient } from "@tanstack/react-query";
+import { ModuleKeys } from "./keys";
+import { ModuleService } from "./services";
+
+export const ModuleMutations = {
+  create_query_name_example: (queryClient: QueryClient) =>
+    mutationOptions({
+      mutationFn: (newItem: any) =>
+        ModuleService.post_query_name_example(newItem),
+      onMutate: async (newItem: any) => {
+        /* 
+        # OPTIMISTIC UPDATE TECHNIQUE:
+        1. Cancel outgoing refetches so they don't overwrite our optimistic update.
+        2. Snapshot the current cache value.
+        3. Optimistically insert the new item into the cache.
+        4. Return context containing the previous value for error rollbacks.
+
+        # EDGE CASE:
+        setQueryData updates the raw cached query data, not the value returned by a query select mapper.
+        Match this optimistic shape to the actual API response shape stored in the cache.
+        */
+        await queryClient.cancelQueries({ queryKey: ModuleKeys.fetch_query_name_example() });
+
+        const previousItems = queryClient.getQueryData(ModuleKeys.fetch_query_name_example());
+
+        queryClient.setQueryData(ModuleKeys.fetch_query_name_example(), (old: any) => {
+          return old ? [...old, newItem] : [newItem];
+        });
+
+        return { previousItems };
+      },
+      onSuccess: async () => {
+        /* 
+        # NOTE: In case of mutations, invalidate query keys to refresh with fresh server data.
+        */
+        await queryClient.invalidateQueries({
+          queryKey: ModuleKeys.fetch_query_name_example(),
+        });
+      },
+      onError: (error, newItem, context: any) => {
+        /* 
+        # ROLLBACK ON FAILURE:
+        If the mutation fails, rollback the cache to our snapshotted state.
+        */
+        if (context?.previousItems) {
+          queryClient.setQueryData(
+            ModuleKeys.fetch_query_name_example(),
+            context.previousItems
+          );
+        }
+      },
+      onSettled: async () => {
+        // Always refetch after error or success to keep server state authoritative after optimistic changes.
+        await queryClient.invalidateQueries({
+          queryKey: ModuleKeys.fetch_query_name_example(),
+        });
+      },
+    }),
+};

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

@@ -1,156 +1,145 @@
-import {
-  queryOptions,
-  infiniteQueryOptions,
-  keepPreviousData,
-} from "@tanstack/react-query";
-
-import { ModuleKeys } from "./keys";
-import { ModuleMappers } from "./mappers";
-import { ModuleService } from "./services";
-
-export const ModuleQueries = {
-  fetch_query_name_example: () =>
-    queryOptions({
-      queryKey: ModuleKeys.fetch_query_name_example(),
-      queryFn: () => {
-        /* 
-        # NOTE:  ModuleService.get_query_name_example() -> hits the api of query fetch or GET
-        Return the Promise directly to TanStack Query so it can natively handle retries and error states.
-        */
-        return ModuleService.get_query_name_example();
-      },
-      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).
-        */
-        return ModuleMappers.fetch_query_name_example(raw as any);
-      },
-      /* 
-      # NOTE: keeps the last successfully fetched data visible on screen 
-      while fetching new data or if a subsequent fetch fails (preventing layout flickers/empty states).
-      */
-      placeholderData: keepPreviousData,
-    }),
-
-  fetch_infinite_query_example: () =>
-    infiniteQueryOptions({
-      queryKey: ModuleKeys.fetch_infinite_query_name_example(),
-      queryFn: ({ pageParam = 1 }) => {
-        /* 
-        # NOTE:  ModuleService.get_infinite_query_example(pageParam) -> hits the api of query fetch or GET
-        Return the Promise directly to TanStack Query so it can natively handle retries and error states.
-        */
-        return ModuleService.get_infinite_query_example(pageParam as number);
-      },
-      getNextPageParam: (raw: any) => {
-        // --- Option A: Cursor-based Pagination ---
-        // return raw.nextCursor ?? undefined;
-
-        // --- Option B: Page-number Metadata Pagination (last_page, current_page) ---
-        // Access metadata from the 'meta' object returned in your API response
-        const { current_page, last_page } = raw?.meta || {};
-        const hasMore = current_page < last_page;
-        return hasMore ? current_page + 1 : undefined;
-      },
-      initialPageParam: 1,
-      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).
-        */
-        return {
-          pages: raw.pages.map((pageData: any) => ({
-            ...pageData,
-            data: ModuleMappers.fetch_infinite_query_example(pageData.data),
-          })),
-          pageParams: raw.pageParams,
-        };
-      },
-      placeholderData: keepPreviousData,
-    }),
-
-  fetch_query_with_params_example: (params: Record<string, any>) =>
-    queryOptions({
-      queryKey: ModuleKeys.fetch_query_with_params_example(params),
-      queryFn: ({ signal }) => {
-        /* 
-        # NOTE: Pass the native 'signal' from the TanStack queryFn context down to the service call.
-        This enables automatic cancellation if query parameters change or the component unmounts.
-        */
-        return ModuleService.get_query_with_params_example(params, signal);
-      },
-      select: raw => {
-        // Reusing the same mapper example for consistency
-        return ModuleMappers.fetch_query_name_example(raw as any);
-      },
-      placeholderData: keepPreviousData,
-    }),
-
-  fetch_query_by_id_example: (id?: string | null) =>
-    queryOptions({
-      queryKey: ModuleKeys.fetch_query_by_id_example(id || ""),
-      queryFn: ({ signal }) => {
-        return ModuleService.get_query_by_id_example(id!, signal);
-      },
-      select: raw => {
-        return ModuleMappers.fetch_query_name_example(raw as any);
-      },
-      placeholderData: keepPreviousData,
-      /* 
-      # NOTE: Conditional/Dependent Queries
-      Setting 'enabled: !!id' stops the query from executing automatically if the ID is missing (undefined, null, or empty).
-      */
-      enabled: !!id,
-    }),
-
-  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 => {
-        return ModuleMappers.fetch_query_name_example(raw as any);
-      },
-      placeholderData: keepPreviousData,
-      enabled: !!id, // Automatically stops API call if ID is null/undefined
-    }),
-};
-
-/*
-# NOTE: RAW DATA VS. MAPPED DATA & MEMOIZATION
-
-1. **Where Raw Data Lives:**
-   - The raw response returned by the API (`queryFn`) is stored unmodified inside the **TanStack Query Cache**. 
-   - This represents the exact payload from your backend database/server.
-
-2. **Where Mapped Data Lives:**
-   - The mapped data is delivered directly to the **UI / React Component** consuming the hook.
-   - It is calculated on-the-fly by executing the `select` function on the cached raw data.
-
-3. **How Memoization Works (Performance Optimization):**
-   - 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;
-    }
-*/
+import { queryOptions, infiniteQueryOptions, keepPreviousData } from "@tanstack/react-query";
+
+import { ModuleKeys } from "./keys";
+import { ModuleMappers } from "./mappers";
+import { ModuleService } from "./services";
+
+export const ModuleQueries = {
+  fetch_query_name_example: () =>
+    queryOptions({
+      queryKey: ModuleKeys.fetch_query_name_example(),
+      queryFn: () => {
+        /* 
+        # NOTE:  ModuleService.get_query_name_example() -> hits the api of query fetch or GET
+        Return the Promise directly to TanStack Query so it can natively handle retries and error states.
+        */
+        return ModuleService.get_query_name_example();
+      },
+      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).
+        */
+        return ModuleMappers.fetch_query_name_example(raw as any);
+      },
+      /* 
+      # NOTE: keeps the last successfully fetched data visible on screen 
+      while fetching new data or if a subsequent fetch fails (preventing layout flickers/empty states).
+      */
+      placeholderData: keepPreviousData,
+    }),
+
+  fetch_infinite_query_example: () =>
+    infiniteQueryOptions({
+      queryKey: ModuleKeys.fetch_infinite_query_name_example(),
+      queryFn: ({ pageParam = 1 }) => {
+        /* 
+        # NOTE:  ModuleService.get_infinite_query_example(pageParam) -> hits the api of query fetch or GET
+        Return the Promise directly to TanStack Query so it can natively handle retries and error states.
+        */
+        return ModuleService.get_infinite_query_example(pageParam as number);
+      },
+      getNextPageParam: (raw: any) => {
+        // --- Option A: Cursor-based Pagination ---
+        // return raw.nextCursor ?? undefined;
+
+        // --- Option B: Page-number Metadata Pagination (last_page, current_page) ---
+        // Access metadata from the 'meta' object returned in your API response
+        const { current_page, last_page } = raw?.meta || {};
+        const hasMore = current_page < last_page;
+        return hasMore ? current_page + 1 : undefined;
+      },
+      initialPageParam: 1,
+      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).
+        */
+        return {
+          pages: raw.pages.map((pageData: any) => ({
+            ...pageData,
+            data: ModuleMappers.fetch_infinite_query_example(pageData.data),
+          })),
+          pageParams: raw.pageParams,
+        };
+      },
+      placeholderData: keepPreviousData,
+    }),
+
+  fetch_query_with_params_example: (params: Record<string, any>) =>
+    queryOptions({
+      /*
+      # NOTE: Include every server-facing filter in the query key.
+      TanStack Query uses this key to cache separate results and cancel/refetch when filters change.
+      */
+      queryKey: ModuleKeys.fetch_query_with_params_example(params),
+      queryFn: ({ signal }) => {
+        /* 
+        # NOTE: Pass the native 'signal' from the TanStack queryFn context down to the service call.
+        This enables automatic cancellation if query parameters change or the component unmounts.
+        */
+        return ModuleService.get_query_with_params_example(params, signal);
+      },
+      select: (raw) => {
+        // Reusing the same mapper example for consistency
+        return ModuleMappers.fetch_query_name_example(raw as any);
+      },
+      placeholderData: keepPreviousData,
+    }),
+
+  fetch_query_by_id_example: (id?: string | null) =>
+    queryOptions({
+      /*
+      # NOTE: Keep the query key stable even before the ID exists.
+      The enabled flag below prevents the request from running with this fallback value.
+      */
+      queryKey: ModuleKeys.fetch_query_by_id_example(id || ""),
+      queryFn: ({ signal }) => {
+        return ModuleService.get_query_by_id_example(id!, signal);
+      },
+      select: (raw) => {
+        return ModuleMappers.fetch_query_name_example(raw as any);
+      },
+      placeholderData: keepPreviousData,
+      /* 
+      # NOTE: Conditional/Dependent Queries
+      Setting 'enabled: !!id' stops the query from executing automatically if the ID is missing (undefined, null, or empty).
+      */
+      enabled: !!id,
+    }),
+
+  fetch_query_combo_example: (id: string | null | undefined, params: Record<string, any>) =>
+    queryOptions({
+      /*
+      # NOTE: Combo keys should include both route identity and filters.
+      This prevents cached data for one ID/filter pair from showing under another pair.
+      */
+      queryKey: ModuleKeys.fetch_query_combo_example(id || "", params),
+      queryFn: ({ signal }) => {
+        return ModuleService.get_query_combo_example(id!, params, signal);
+      },
+      select: (raw) => {
+        return ModuleMappers.fetch_query_name_example(raw as any);
+      },
+      placeholderData: keepPreviousData,
+      enabled: !!id, // Automatically stops API call if ID is null/undefined
+    }),
+};
+
+/*
+# NOTE: RAW DATA VS. MAPPED DATA & MEMOIZATION
+
+1. **Where Raw Data Lives:**
+   - The raw response returned by the API (`queryFn`) is stored unmodified inside the **TanStack Query Cache**. 
+   - This represents the exact payload from your backend database/server.
+
+2. **Where Mapped Data Lives:**
+   - The mapped data is delivered directly to the **UI / React Component** consuming the hook.
+   - It is calculated on-the-fly by executing the `select` function on the cached raw data.
+
+3. **How Memoization Works (Performance Optimization):**
+   - 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.
+*/
+

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

@@ -1,66 +1,74 @@
-import { apiClient } from "../client";
-
-export const ModuleService = {
-  get_query_name_example: () => apiClient.get("/api_name/get"),
-  get_infinite_query_example: (page: number) =>
-    apiClient.get(`/api_name/list?page=${page}`),
-  get_query_with_params_example: (params: Record<string, any>, signal?: AbortSignal) => {
-    const queryParams = new URLSearchParams();
-    Object.entries(params).forEach(([key, value]) => {
-      if (Array.isArray(value)) {
-        value.forEach((val) => {
-          if (val !== undefined && val !== null && val !== "") {
-            queryParams.append(key, String(val));
-          }
-        });
-      } else if (value !== undefined && value !== null && value !== "") {
-        queryParams.set(key, String(value));
-      }
-    });
-    return apiClient.get(`/api_name/get-with-params?${queryParams.toString()}`, { signal });
-  },
-  get_query_by_id_example: (id: string, signal?: AbortSignal) =>
-    apiClient.get(`/api_name/get-by-id/${id}`, { signal }),
-  get_query_combo_example: (id: string, params: Record<string, any>, signal?: AbortSignal) => {
-    const queryParams = new URLSearchParams();
-    Object.entries(params).forEach(([key, value]) => {
-      if (Array.isArray(value)) {
-        value.forEach((val) => {
-          if (val !== undefined && val !== null && val !== "") {
-            queryParams.append(key, String(val));
-          }
-        });
-      } else if (value !== undefined && value !== null && value !== "") {
-        queryParams.set(key, String(value));
-      }
-    });
-    return apiClient.get(`/api_name/get-combo/${id}?${queryParams.toString()}`, { signal });
-  },
-  post_query_name_example: (input: any) =>
-    apiClient.post("/api_name/post", input),
-  patch_query_name_example: (input: any) =>
-    apiClient.patch("/api_name/patch", input),
-  delete_query_name_example: (id: string) =>
-    apiClient.delete(`/api_name/${id}`),
-};
-
-/* 
-# NOTE: you can change *_name_example to your own query name
-# NOTE: you can change /api_name to your own api name
-# NOTE: you can change input to your own data type
-# NOTE: you can change id to your own data type
-
--------------------------------------------------------------------------
-
-# NOTE: WHY WE USE URLSearchParams & THE ROLE OF THE SERVICE LAYER
-
-1. **Why we use `URLSearchParams`:**
-   - **Automatic URL-Encoding:** It automatically sanitizes special characters (like spaces, commas, or quotes) into browser-safe formats (e.g., space becomes `%20`), preventing broken URLs.
-   - **Dynamic Query String Building:** It generates the final string from a raw object dynamically (calling `.toString()` results in `key1=val1&key2=val2`).
-
-2. **Role of this Service Layer (`get_query_with_params_example`):**
-   - **Decoupled Contracts:** It keeps components "dumb" about network specifics. The component only needs to pass a clean JavaScript object containing the filters.
-   - **Centralization:** If endpoints change or parameter serialization logic needs to adjust in the future, it is managed in this single file rather than modifying multiple UI files.
-*/
-
-
+import { apiClient } from "../client";
+
+export const ModuleService = {
+  get_query_name_example: () => apiClient.get("/api_name/get"),
+  get_infinite_query_example: (page: number) =>
+    apiClient.get(`/api_name/list?page=${page}`),
+  get_query_with_params_example: (params: Record<string, any>, signal?: AbortSignal) => {
+    const queryParams = new URLSearchParams();
+    Object.entries(params).forEach(([key, value]) => {
+      /*
+      # NOTE: Arrays become repeated keys, e.g. brands=samsung&brands=apple.
+      Empty values are skipped so default UI state does not create noisy URLs.
+      */
+      if (Array.isArray(value)) {
+        value.forEach((val) => {
+          if (val !== undefined && val !== null && val !== "") {
+            queryParams.append(key, String(val));
+          }
+        });
+      } else if (value !== undefined && value !== null && value !== "") {
+        queryParams.set(key, String(value));
+      }
+    });
+    return apiClient.get(`/api_name/get-with-params?${queryParams.toString()}`, { signal });
+  },
+  get_query_by_id_example: (id: string, signal?: AbortSignal) =>
+    apiClient.get(`/api_name/get-by-id/${id}`, { signal }),
+  get_query_combo_example: (id: string, params: Record<string, any>, signal?: AbortSignal) => {
+    const queryParams = new URLSearchParams();
+    Object.entries(params).forEach(([key, value]) => {
+      /*
+      # NOTE: Reuse the same serialization rules for route-specific filtered requests.
+      Keeping this logic centralized avoids components building query strings by hand.
+      */
+      if (Array.isArray(value)) {
+        value.forEach((val) => {
+          if (val !== undefined && val !== null && val !== "") {
+            queryParams.append(key, String(val));
+          }
+        });
+      } else if (value !== undefined && value !== null && value !== "") {
+        queryParams.set(key, String(value));
+      }
+    });
+    return apiClient.get(`/api_name/get-combo/${id}?${queryParams.toString()}`, { signal });
+  },
+  post_query_name_example: (input: any) =>
+    apiClient.post("/api_name/post", input),
+  patch_query_name_example: (input: any) =>
+    apiClient.patch("/api_name/patch", input),
+  delete_query_name_example: (id: string) =>
+    apiClient.delete(`/api_name/${id}`),
+};
+
+/* 
+# NOTE: you can change *_name_example to your own query name
+# NOTE: you can change /api_name to your own api name
+# NOTE: you can change input to your own data type
+# NOTE: you can change id to your own data type
+
+-------------------------------------------------------------------------
+
+# NOTE: WHY WE USE URLSearchParams & THE ROLE OF THE SERVICE LAYER
+
+1. **Why we use `URLSearchParams`:**
+   - **Automatic URL-Encoding:** It automatically sanitizes special characters (like spaces, commas, or quotes) into browser-safe formats (e.g., space becomes `%20`), preventing broken URLs.
+   - **Dynamic Query String Building:** It generates the final string from a raw object dynamically (calling `.toString()` results in `key1=val1&key2=val2`).
+
+2. **Role of this Service Layer (`get_query_with_params_example`):**
+   - **Decoupled Contracts:** It keeps components "dumb" about network specifics. The component only needs to pass a clean JavaScript object containing the filters.
+   - **Centralization:** If endpoints change or parameter serialization logic needs to adjust in the future, it is managed in this single file rather than modifying multiple UI files.
+*/
+
+

package/templates/scaffolds/tanstack-router/layout/404.layout.tsx

@@ -0,0 +1,3 @@
+export default function PageNotFound () {
+  return <div>404 layout</div>;
+}

package/templates/scaffolds/tanstack-router/layout/app.layout.tsx

@@ -0,0 +1,10 @@
+import { Outlet } from "@tanstack/react-router";
+
+export default function AppLayout() {
+  return (
+    <>
+      <div>App Section Static</div>
+      <Outlet />
+    </>
+  );
+}

package/templates/scaffolds/tanstack-router/layout/auth.layout.tsx

@@ -0,0 +1,10 @@
+import { Outlet } from "@tanstack/react-router";
+
+export default function AuthLayout() {
+  return (
+    <>
+      <div>Auth Section Static</div>
+      <Outlet />
+    </>
+  );
+}

package/templates/scaffolds/tanstack-router/layout/error.layout.tsx

@@ -0,0 +1,3 @@
+export default function ErrorLayout() {
+  return <div>Something went wrong.</div>;
+}

package/templates/scaffolds/tanstack-router/page/auth/login.tsx

@@ -0,0 +1,3 @@
+export default function Login() {
+  return <>This is login page</>;
+}