pejay-ui 1.3.2 → 1.3.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pejay-ui",
-  "version": "1.3.2",
+  "version": "1.3.3",
   "type": "module",
   "description": "react ui components",
   "bin": {

package/templates/notes/analysis_results.md

@@ -0,0 +1,107 @@
+# Codebase Scaffold Audit & Analysis
+
+This document provides a comprehensive structural and architectural analysis of the scaffold templates in `pejay-ui` (`templates/scaffolds/`). All scaffolds are ready-to-use boilerplate templates designed to be easily injected into react-based projects using the CLI.
+
+---
+
+## 1. Axios Scaffold (`axios-client`)
+* **Target Directory**: `src/axios/`
+* **Peer Dependencies**: `axios`
+* **Files**:
+  * `index.ts`: Configures the base `axiosInstance` with a local port 5001 base URL and default configurations.
+  * `interceptors.ts`: Configures standard request and response interceptors.
+  * `request.ts`: Implements a type-safe wrapper over `axios` queries with customized `CustomAxiosRequestConfig` options (such as `skipErrorToast`).
+  * `endpoints.ts`: Declarative endpoint configurations helper (`createResourceEndpoints`).
+  * `api/one.api.ts` & `index.ts`: Implements API wrapper services mapping HTTP verbs (GET, POST, PUT, DELETE, and multipart/form-data POST) using endpoints.
+
+### 💡 Notable Architectural Design Patterns
+* **Token Injection & Eject Pattern**: Setup function allows on-demand ejection of previous interceptors to prevent interceptor duplication when token state resets.
+* **Multipart uploads**: Out-of-the-box helper configuration for `multipart/form-data` uploading.
+* **Commented Best Practice Guides**: Includes detailed code comments discussing error handling strategies (global vs. screen-specific alerts like 400 Validation, 422 Forms, 409 Conflicts).
+
+---
+
+## 2. React Router Scaffold (`react-router-client`)
+* **Target Directory**: `src/react-router/`
+* **Peer Dependencies**: `react-router-dom`
+* **Files**:
+  * `router/index.ts`: Builds the route hierarchy using the modern object-based router syntax (`createBrowserRouter`).
+  * `router/path.ts`: Declares route path constants.
+  * `router/guards/private.route.tsx` & `public.route.tsx`: Authentication routing guards.
+  * `router/layouts/`: Base layout wrapper components (`auth.layout.tsx`, `error.layout.tsx`, `main.layout.tsx`).
+  * `routes/`: Subfolders representing each page boundary with lazy component imports.
+  * `hook/useRouterSearch.ts`: Utility hook for robust search parameter reading.
+
+### 💡 Notable Architectural Design Patterns
+* **Route Guards without Paths**: Centralizes auth decisions using pathless routes (layout routes) that encapsulate authentication checks before child route components mount.
+* **Target Restoration Pattern**: कमेंट-दस्तावेज demonstrates how the private route guard passes `redirectTo` in query parameters, allowing the login flow to restore user navigation state seamlessly.
+* **SEO & Static Prerendering (V7)**: Extensive documentation within route components illustrating route meta configurations and Nginx deployment configurations for serving pre-rendered static HTML structures.
+
+---
+
+## 3. Redux Store Scaffold (`redux-store-client`)
+* **Target Directory**: `src/redux-store/`
+* **Peer Dependencies**: `@reduxjs/toolkit`, `react-redux`, `redux-persist`
+* **Files**:
+  * `store.ts`: Configures store via `configureStore` with middleware handling to bypass serialization warnings for `redux-persist` actions.
+  * `reducers.ts`: Combines slices, setting up selective slice persistence configurations.
+  * `slices/`: Example RTK slices (`one.slice.ts` & `two.slice.ts`) containing state declarations, actions, and reducers.
+  * `selector/`: Selectors implementing memoized state reading.
+
+### 💡 Notable Architectural Design Patterns
+* **Bypassing Redux-Persist Serialization Warnings**: Custom configureStore config overrides standard serialization check constraints to allow redux-persist lifecycle actions (`FLUSH`, `REHYDRATE`, etc.) without throwing warnings.
+* **Slice-Level Persistence Configuration**: Configured to show developers how to selectively persist specific slices using `storageLocal` instead of forcing entire store persistence.
+
+---
+
+## 4. RTK Query Scaffold (`rtk-query-client`)
+* **Target Directory**: `src/rtk-query/`
+* **Peer Dependencies**: `@reduxjs/toolkit`, `react-redux`
+* **Files**:
+  * `baseApi.ts`: Initial API framework setup using `createApi` and injecting custom base queries.
+  * `baseQuery.ts`: Configures base query parameters.
+  * `queryTags.ts`: Declarative cache tag declarations.
+  * `middlewares.ts`: RTK query middleware definitions.
+  * `endpoints/`: Route query endpoint modules.
+
+### 💡 Notable Architectural Design Patterns
+* **Centralized Cache Tag Management**: Centralizes tag types in a single array mapping configuration to prevent magic strings and cache invalidation issues.
+* **Ready-to-Plug Store Middleware**: Clear documentation showing how to connect RTK Query's reducer and middleware inside the primary Redux root store.
+
+---
+
+## 5. TanStack Query Scaffold (`tanstack-query-client`)
+* **Target Directory**: `src/tanstack-query/`
+* **Peer Dependencies**: `@tanstack/react-query`
+* **Files**:
+  * `client.ts`: Configures a custom type-safe `apiClient` wrapper around the web fetch API.
+  * `api-base.ts`: Standard configuration settings.
+  * `api-queries.ts` / `api-mutations.ts`: API query hooks.
+  * `module/`: Modular services, mutations, queries, mappers, and cache keys configuration.
+
+### 💡 Notable Architectural Design Patterns
+* **Type-Safe API Wrapper Client**: Provides custom `.get()`, `.post()`, `.put()`, `.patch()`, and `.delete()` wrappers on `fetch` with automated JSON serialization guards.
+* **Separation of Concerns**: Structures files with clean mappers (decoupling API responses from UI representations) and query key factories (avoiding string typos).
+
+---
+
+## 6. TanStack Router Scaffold (`tanstack-router-client`)
+* **Target Directory**: `src/tanstack-router/`
+* **Peer Dependencies**: `@tanstack/react-router`
+* **Files**:
+  * `router.ts`: Initializes Tanstack `createRouter` and configures defaults.
+  * `routes/`: File-based route trees (`__root.tsx`, `_app.tsx`, `_auth.tsx`).
+  * `layout/`: UI layouts (`app.layout.tsx`, `auth.layout.tsx`, etc.).
+  * `page/`: Visual target pages.
+
+### 💡 Notable Architectural Design Patterns
+* **Intent-Based Preloading**: Uses `defaultPreload: "intent"` to preload route bundles and datasets immediately when a user hovers over a link, maximizing perceived UI responsiveness.
+* **TypeScript Route Declaration Merging**: Employs TypeScript interface merging (`Register`) to ensure global route tree parameters are fully typed across the application.
+
+---
+
+## 🛠️ Verification & Quality Assessment
+
+* **Relative Imports**: All internal template files reference other module files using relative imports (`./` or `../`). They do not depend on absolute webpack/vite aliases (e.g. `@/`), making them immediately compatible with any folder structure they are copied into.
+* **Code Cleanliness**: Types are cleanly defined, variables are appropriately scoped, and hooks clean up event listeners on unmount.
+* **Documentation Quality**: Comments explain the architectural "Why" (e.g., Suspense vs Component Skeletons, SEO Nginx server setup) instead of just repeating what the code does. This is extremely helpful for developers installing these scaffolds.

package/templates/scripts/setup.bat

@@ -29,21 +29,25 @@ echo.
 
 set "packages="
 
-call :ask "@reduxjs/toolkit"
 call :ask "@tailwindcss/vite"
+call :ask "tailwindcss"
+call :ask "tailwind-merge"
 call :ask "clsx"
-call :ask "date-fns"
-call :ask "dayjs"
-call :ask "@floating-ui/react"
-call :ask "lucide-react"
 call :ask "react-hook-form"
-call :ask "react-redux"
 call :ask "react-router-dom"
-call :ask "tailwind-merge"
-call :ask "tailwindcss"
 call :ask "@tanstack/react-query"
-call :ask "zod"
+call :ask "@tanstack/react-router"
+call :ask "@reduxjs/toolkit"
+call :ask "react-redux"
+call :ask "redux-persist"
+call :ask "lucide-react"
+call :ask "react-icons"
+call :ask "axios"
 call :ask "zustand"
+call :ask "zod"
+call :ask "@hookform/resolvers"
+call :ask "@floating-ui/react"
+call :ask "framer-motion"
 
 if not "!packages!"=="" (
     echo.
@@ -222,51 +226,90 @@ type nul > components\global\index.ts
 mkdir hooks
 type nul > hooks\index.ts
 
-mkdir lib
-type nul > lib\index.ts
-
-mkdir routes
-type nul > routes\index.ts
-mkdir routes\dashboard
-type nul > routes\dashboard\index.ts
-mkdir routes\dashboard\components
-type nul > routes\dashboard\components\index.ts
-mkdir routes\dashboard\hooks
-type nul > routes\dashboard\hooks\index.ts
-mkdir routes\auth
-type nul > routes\auth\index.ts
-mkdir routes\auth\components
-type nul > routes\auth\components\index.ts
-mkdir routes\auth\hooks
-type nul > routes\auth\hooks\index.ts
-
-mkdir router
-mkdir router\guards
-type nul > router\guards\guard.public.ts
-type nul > router\guards\guard.private.ts
-mkdir router\layout
-type nul > router\layout\layout.public.ts
-type nul > router\layout\layout.main.ts
-type nul > router\layout\layout.auth.ts
-type nul > router\index.ts
-
-mkdir providers
-type nul > providers\index.ts
-type nul > providers\app.provider.ts
-
-mkdir services
-type nul > services\index.ts
-mkdir services\dashboard
-mkdir services\auth
-
-mkdir store
-type nul > store\index.ts
-
 mkdir utils
 type nul > utils\index.ts
 
 cd ..
 
+:: ─────────────────────────────────────────
+:: pejay-ui initialization and scaffolding
+:: ─────────────────────────────────────────
+set "hasAxios="
+set "hasTanstackQuery="
+set "hasTanstackRouter="
+set "hasReactRouter="
+set "hasRedux="
+set "hasPersist="
+
+for %%p in (!packages!) do (
+    if "%%p"=="axios" set "hasAxios=1"
+    if "%%p"=="@tanstack/react-query" set "hasTanstackQuery=1"
+    if "%%p"=="@tanstack/react-router" set "hasTanstackRouter=1"
+    if "%%p"=="react-router-dom" set "hasReactRouter=1"
+    if "%%p"=="@reduxjs/toolkit" set "hasRedux=1"
+    if "%%p"=="react-redux" set "hasRedux=1"
+    if "%%p"=="redux-persist" set "hasPersist=1"
+)
+
+set "needsInit="
+if defined hasAxios set "needsInit=1"
+if defined hasTanstackQuery set "needsInit=1"
+if defined hasTanstackRouter set "needsInit=1"
+if defined hasReactRouter set "needsInit=1"
+if defined hasRedux set "needsInit=1"
+
+if defined needsInit (
+    echo.
+    echo Initializing pejay-ui...
+    call npx pejay-ui init
+    
+    if defined hasAxios (
+        echo Adding axios-client...
+        call npx pejay-ui add axios-client
+    )
+    if defined hasTanstackQuery (
+        echo Adding tanstack-query-client...
+        call npx pejay-ui add tanstack-query-client
+    )
+    if defined hasTanstackRouter (
+        echo Adding tanstack-router-client...
+        call npx pejay-ui add tanstack-router-client
+    )
+    if defined hasReactRouter (
+        echo Adding react-router-client...
+        call npx pejay-ui add react-router-client
+    )
+    if defined hasRedux (
+        if defined hasPersist (
+            echo Adding redux-store-client...
+            call npx pejay-ui add redux-store-client
+        ) else (
+            echo.
+            echo You selected Redux. Which template would you like to add?
+            echo [1] Redux Store (redux-store-client)
+            echo [2] RTK Query (rtk-query-client)
+            echo [3] Both
+            echo [4] None
+            set "reduxAns=1"
+            set /p "reduxAns=Enter choice (1-4, default 1): "
+            if "!reduxAns!"=="2" (
+                echo Adding rtk-query-client...
+                call npx pejay-ui add rtk-query-client
+            ) else if "!reduxAns!"=="3" (
+                echo Adding redux-store-client...
+                call npx pejay-ui add redux-store-client
+                echo Adding rtk-query-client...
+                call npx pejay-ui add rtk-query-client
+            ) else if "!reduxAns!"=="4" (
+                rem Do nothing
+            ) else (
+                echo Adding redux-store-client...
+                call npx pejay-ui add redux-store-client
+            )
+        )
+    )
+)
+
 echo.
 echo Project '%projectName%' setup complete!
 endlocal

package/templates/scripts/setup.ps1

@@ -63,28 +63,33 @@ Write-Output "Installing dependencies"
 
 
 $availablePackages = @(
-    "@reduxjs/toolkit",
     "@tailwindcss/vite",
+    "tailwindcss",
+    "tailwind-merge",
     "clsx",
-    "date-fns",
-    "dayjs",
-    "floating-ui",
-    "lucide-react",
-    "react-form-hook",
-    "react-redux",
+    "react-hook-form",
     "react-router-dom",
-    "tailwind-merge",
-    "tailwindcss",
-    "tanstack-query",
+    "@tanstack/react-query",
+    "@tanstack/react-router",
+    "@reduxjs/toolkit",
+    "react-redux",
+    "redux-persist",
+    "lucide-react",
+    "react-icons",
+    "axios",   
+    "zustand",
     "zod",
-    "zustand"
+    "@hookform/resolvers",
+    "@floating-ui/react",
+    "framer-motion"
 )
 
 $selectedPackages = Show-MultiSelect -Options $availablePackages -Title "Select packages to install (SPACE to toggle, ENTER to confirm):"
 
 if ($selectedPackages.Count -gt 0) {
     npm install
-    npm install $selectedPackages
+    $packageString = $selectedPackages -join " "
+    Invoke-Expression "npm install $packageString"
 } else {
     Write-Output "No packages selected, skipping..."
 }
@@ -270,49 +275,66 @@ Set-Content "components/global/index.ts" ""
 mkdir hooks
 Set-Content "hooks/index.ts" ""
 
-mkdir lib
-Set-Content "lib/index.ts" ""
-
-mkdir routes
-Set-Content "routes/index.ts" ""
-mkdir routes/dashboard
-Set-Content "routes/dashboard/index.ts" ""
-mkdir routes/dashboard/components
-Set-Content "routes/dashboard/components/index.ts" ""
-mkdir routes/dashboard/hooks
-Set-Content "routes/dashboard/hooks/index.ts" ""
-mkdir routes/auth
-Set-Content "routes/auth/index.ts" ""
-mkdir routes/auth/components
-Set-Content "routes/auth/components/index.ts" ""
-mkdir routes/auth/hooks
-Set-Content "routes/auth/hooks/index.ts" ""
-
-mkdir router
-mkdir router/guards
-Set-Content "router/guards/guard.public.ts" ""
-Set-Content "router/guards/guard.private.ts" ""
-mkdir router/layout
-Set-Content "router/layout/layout.public.ts" ""
-Set-Content "router/layout/layout.main.ts" ""
-Set-Content "router/layout/layout.auth.ts" ""
-Set-Content "router/index.ts" ""
-
-mkdir providers
-Set-Content "providers/index.ts" ""
-Set-Content "providers/app.provider.ts" ""
-
-mkdir services
-Set-Content "services/index.ts" ""
-mkdir services/dashboard
-mkdir services/auth
-
-mkdir store
-Set-Content "store/index.ts" ""
-
 mkdir utils
 Set-Content "utils/index.ts" ""
 
 Set-Location ..
 
+# ─────────────────────────────────────────
+# pejay-ui initialization and scaffolding
+# ─────────────────────────────────────────
+$needsInit = $false
+$templatesToAdd = @()
+
+if ($selectedPackages -contains "axios") {
+    $needsInit = $true
+    $templatesToAdd += "axios-client"
+}
+if ($selectedPackages -contains "@tanstack/react-query") {
+    $needsInit = $true
+    $templatesToAdd += "tanstack-query-client"
+}
+if ($selectedPackages -contains "@tanstack/react-router") {
+    $needsInit = $true
+    $templatesToAdd += "tanstack-router-client"
+}
+if ($selectedPackages -contains "react-router-dom") {
+    $needsInit = $true
+    $templatesToAdd += "react-router-client"
+}
+if ($selectedPackages -contains "@reduxjs/toolkit" -or $selectedPackages -contains "react-redux") {
+    $needsInit = $true
+    if ($selectedPackages -contains "redux-persist") {
+        $templatesToAdd += "redux-store-client"
+    } else {
+        Write-Output ""
+        Write-Output "You selected Redux. Which template would you like to add?"
+        Write-Output "1) Redux Store (redux-store-client)"
+        Write-Output "2) RTK Query (rtk-query-client)"
+        Write-Output "3) Both"
+        Write-Output "4) None"
+        $reduxChoice = Read-Host "Select option (1-4, default 1)"
+        if ($reduxChoice -eq "2") {
+            $templatesToAdd += "rtk-query-client"
+        } elseif ($reduxChoice -eq "3") {
+            $templatesToAdd += "redux-store-client"
+            $templatesToAdd += "rtk-query-client"
+        } elseif ($reduxChoice -eq "4") {
+            # None
+        } else {
+            $templatesToAdd += "redux-store-client"
+        }
+    }
+}
+
+if ($needsInit) {
+    Write-Output "`nInitializing pejay-ui..."
+    npx pejay-ui init
+
+    foreach ($template in $templatesToAdd) {
+        Write-Output "Adding template: $template..."
+        npx pejay-ui add $template
+    }
+}
+
 Write-Output "✅ Project '$projectName' setup complete!"