vasuzex 2.3.2 → 2.3.4

package/framework/Foundation/BaseApp.js

@@ -139,6 +139,11 @@ export class BaseApp extends Application {
    * Core middleware for parsing JSON and URL-encoded request bodies
    */
   setupBodyParsing() {
+    // Configure query parser to support nested bracket notation (e.g. filters[name]=value)
+    // Express 5 defaults to 'simple' (Node's querystring) which does not parse brackets
+    // 'extended' uses qs.parse which correctly handles nested objects
+    this.express.set('query parser', 'extended');
+
     // Parse JSON request bodies
     this.express.use(express.json());
     

package/frontend/react-ui/components/DataTable/DataTable.jsx

@@ -10,7 +10,7 @@
  * - Rows per page selector
  * - Action buttons (edit/view/delete/switch)
  * - Loading and empty states
- * - State persistence (restores page/filters when navigating back)
+ * - URL-based state persistence (page, sort, filters in query params)
  * 
  * @module components/DataTable
  */
@@ -22,9 +22,27 @@ import { TableHeader } from "./TableHeader.jsx";
 import { TableState } from "./TableState.jsx";
 import { Pagination } from "./Pagination.jsx";
 
+// Conditional import for React Router (optional dependency)
+let useSearchParamsHook = null;
+let useLocationHook = null;
+
+try {
+  const routerModule = require('react-router-dom');
+  useSearchParamsHook = routerModule.useSearchParams;
+  useLocationHook = routerModule.useLocation;
+} catch (e) {
+  // React Router not available - will use plain window.history
+}
+
 /**
  * Production-ready DataTable with complete server-side functionality
  * 
+ * State is persisted in URL query parameters, ensuring:
+ * - Each page has unique, isolated state
+ * - Browser back/forward buttons work correctly
+ * - Users can bookmark specific table states
+ * - No state bleeding between different DataTables
+ * 
  * @param {Object} props
  * @param {Object} props.api - API client instance (required)
  * @param {string} props.apiUrl - API endpoint for data fetching
@@ -34,13 +52,12 @@ import { Pagination } from "./Pagination.jsx";
  * @param {string} props.resourceName - Resource name for route generation
  * @param {string} props.resourceIdField - ID field name (default: "id")
  * @param {number} props.refreshSignal - External refresh trigger
- * @param {string} props.initialSortBy - Initial sort field
+ * @param {string} props.initialSortBy - Initial sort field (fallback if no URL param)
  * @param {string} props.initialSortOrder - Initial sort order (asc/desc)
  * @param {string} props.initialStatusFilter - Initial status filter (all/true/false)
  * @param {number} props.initialLimit - Initial rows per page
  * @param {string} props.emptyText - Text to show when no data
- * @param {boolean} props.persistState - Enable state persistence (default: true)
- * @param {string} props.stateKey - Custom key for state storage (default: derived from apiUrl)
+ * @param {boolean} props.persistState - Enable URL state persistence (default: true)
  */
 export function DataTable(props) {
   // Internal refresh key for self-refresh
@@ -63,8 +80,7 @@ export function DataTable(props) {
     onDelete,
     onToggle,
     api, // API client instance passed as prop
-    persistState = true, // Enable state persistence by default
-    stateKey, // Optional custom state key
+    persistState = true, // Enable URL-based state persistence by default
   } = props;
 
   // Validate that api client is provided
@@ -72,56 +88,133 @@ export function DataTable(props) {
     throw new Error('DataTable requires "api" prop - pass your API client instance');
   }
 
-  // Generate unique storage key based on apiUrl or custom stateKey
-  const storageKey = React.useMemo(() => {
-    if (stateKey) return `datatable_${stateKey}`;
-    // Use apiUrl as key (remove query params for consistency)
-    const cleanUrl = apiUrl.split('?')[0];
-    return `datatable_${cleanUrl.replace(/[^a-zA-Z0-9]/g, '_')}`;
-  }, [apiUrl, stateKey]);
+  // React Router hooks must be called unconditionally
+  // Call them if available, but handle errors gracefully
+  let searchParams = null;
+  let setSearchParams = null;
+  let location = null;
+  
+  try {
+    if (useSearchParamsHook) {
+      [searchParams, setSearchParams] = useSearchParamsHook();
+    }
+    if (useLocationHook) {
+      location = useLocationHook();
+    }
+  } catch (e) {
+    
+    // Hooks not available or failed - will use window.history
+    searchParams = null;
+    setSearchParams = null;
+    location = null;
+  }
+  
+  const hasReactRouter = !!(searchParams && setSearchParams);
+  
+  
 
-  // Helper to load persisted state
-  const loadPersistedState = React.useCallback(() => {
-    if (!persistState) return null;
-    try {
-      const stored = sessionStorage.getItem(storageKey);
-      return stored ? JSON.parse(stored) : null;
-    } catch (error) {
-      return null;
+  /**
+   * Load state from URL query parameters
+   * This provides natural isolation between different pages/DataTables
+   */
+  const loadStateFromURL = React.useCallback(() => {
+    if (!persistState || typeof window === 'undefined') {
+      return {
+        page: initialPage,
+        sortBy: initialSortBy || (columns.find((c) => c.sortable)?.field) || "",
+        sortOrder: initialSortOrder,
+        search: initialSearch || "",
+        statusFilter: initialStatusFilter || "all",
+        limit: initialLimit || 10,
+        columnSearch: {},
+      };
     }
-  }, [persistState, storageKey]);
 
-  // Helper to save state
-  const saveState = React.useCallback((state) => {
-    if (!persistState) return;
-    try {
-      sessionStorage.setItem(storageKey, JSON.stringify(state));
-    } catch (error) {
-      // Silently fail if sessionStorage is not available
+    // Use React Router searchParams or fallback to URLSearchParams
+    const params = hasReactRouter && searchParams
+      ? searchParams
+      : new URLSearchParams(window.location.search);
+    
+    // Parse column search from URL params (columnSearch[fieldName]=value format)
+    const columnSearch = {};
+    for (const [key, value] of params.entries()) {
+      const match = key.match(/^columnSearch\[(.+)\]$/);
+      if (match && value) {
+        columnSearch[match[1]] = value;
+      }
     }
-  }, [persistState, storageKey]);
+    
+    return {
+      page: parseInt(params.get('page')) || initialPage,
+      sortBy: params.get('sortBy') || initialSortBy || (columns.find((c) => c.sortable)?.field) || "",
+      sortOrder: params.get('sortOrder') || initialSortOrder,
+      search: params.get('search') || initialSearch || "",
+      statusFilter: params.get('statusFilter') || initialStatusFilter || "all",
+      limit: parseInt(params.get('limit')) || initialLimit || 10,
+      columnSearch,
+    };
+  }, [persistState, initialPage, initialSortBy, initialSortOrder, initialSearch, initialStatusFilter, initialLimit, columns, hasReactRouter, searchParams]);
 
-  // Initialize state from persisted data or props
-  const persistedState = loadPersistedState();
+  // Initialize state from URL
+  const urlState = loadStateFromURL();
+  
+  const [page, setPage] = React.useState(urlState.page);
+  const [sortBy, setSortBy] = React.useState(urlState.sortBy);
+  const [sortOrder, setSortOrder] = React.useState(urlState.sortOrder);
+  const [search, setSearch] = React.useState(urlState.search);
+  const [statusFilter, setStatusFilter] = React.useState(urlState.statusFilter);
+  const [limit, setLimit] = React.useState(urlState.limit);
+  const [columnSearch, setColumnSearch] = React.useState(urlState.columnSearch);
   
-  const [page, setPage] = React.useState(persistedState?.page || initialPage);
-  const [sortBy, setSortBy] = React.useState(
-    persistedState?.sortBy || initialSortBy || (columns.find((c) => c.sortable)?.field) || "",
-  );
-  const [sortOrder, setSortOrder] = React.useState(persistedState?.sortOrder || initialSortOrder);
-  const [search, setSearch] = React.useState(persistedState?.search || initialSearch || "");
-  const [statusFilter, setStatusFilter] = React.useState(persistedState?.statusFilter || initialStatusFilter || "all");
-  const [limit, setLimit] = React.useState(persistedState?.limit || initialLimit || 10);
   const [data, setData] = React.useState([]);
   const [loading, setLoading] = React.useState(false);
   const [totalPages, setTotalPages] = React.useState(1);
   const [totalItems, setTotalItems] = React.useState(0);
-  // Column search state
-  const [columnSearch, setColumnSearch] = React.useState(persistedState?.columnSearch || {});
-  
-  // Save state whenever it changes
+
+  /**
+   * Update URL with current state
+   * Uses replaceState to avoid polluting browser history with every filter change
+   * Only includes non-default values to keep URL clean
+   */
+  const updateURL = React.useCallback((state) => {
+    if (!persistState || typeof window === 'undefined') return;
+
+    
+
+    const params = new URLSearchParams();
+    
+    // Only add non-default values to keep URL clean
+    if (state.page !== 1) params.set('page', state.page);
+    if (state.sortBy) params.set('sortBy', state.sortBy);
+    if (state.sortOrder !== initialSortOrder) params.set('sortOrder', state.sortOrder);
+    if (state.search) params.set('search', state.search);
+    if (state.statusFilter !== 'all') params.set('statusFilter', state.statusFilter);
+    if (state.limit !== (initialLimit || 10)) params.set('limit', state.limit);
+    
+    // Add column search params
+    Object.entries(state.columnSearch || {}).forEach(([field, value]) => {
+      if (value) params.set(`columnSearch[${field}]`, value);
+    });
+
+    // Use React Router if available, otherwise window.history
+    if (hasReactRouter && setSearchParams) {
+      
+      setSearchParams(params, { replace: true });
+    } else if (typeof window !== 'undefined') {
+      const newURL = params.toString() 
+        ? `${window.location.pathname}?${params.toString()}`
+        : window.location.pathname;
+      
+      
+      window.history.replaceState({}, '', newURL);
+    }
+  }, [persistState, hasReactRouter, setSearchParams]);
+
+  /**
+   * Sync URL whenever state changes
+   */
   React.useEffect(() => {
-    saveState({
+    updateURL({
       page,
       sortBy,
       sortOrder,
@@ -130,7 +223,57 @@ export function DataTable(props) {
       limit,
       columnSearch,
     });
-  }, [page, sortBy, sortOrder, search, statusFilter, limit, columnSearch, saveState]);
+  }, [page, sortBy, sortOrder, search, statusFilter, limit, columnSearch, updateURL]);
+
+  /**
+   * Handle browser back/forward buttons
+   * Reload state from URL when user navigates
+   */
+  React.useEffect(() => {
+    if (!persistState || typeof window === 'undefined') return;
+    if (hasReactRouter) return; // React Router handles this automatically
+
+    const handlePopState = () => {
+      const newState = loadStateFromURL();
+      setPage(newState.page);
+      setSortBy(newState.sortBy);
+      setSortOrder(newState.sortOrder);
+      setSearch(newState.search);
+      setStatusFilter(newState.statusFilter);
+      setLimit(newState.limit);
+      setColumnSearch(newState.columnSearch);
+    };
+
+    window.addEventListener('popstate', handlePopState);
+    return () => window.removeEventListener('popstate', handlePopState);
+  }, [persistState, loadStateFromURL, hasReactRouter]);
+
+  // For React Router: reload state when location.search changes
+  // Only when React Router and manual browser navigation (not programmatic updates)
+  React.useEffect(() => {
+    if (!hasReactRouter || !location) return;
+    
+    // Avoid reacting to our own updates by checking if state already matches URL    const urlState = loadStateFromURL();
+    const stateChanged = (
+      urlState.page !== page ||
+      urlState.sortBy !== sortBy ||
+      urlState.sortOrder !== sortOrder ||
+      urlState.search !== search ||
+      urlState.statusFilter !== statusFilter ||
+      urlState.limit !== limit ||
+      JSON.stringify(urlState.columnSearch) !== JSON.stringify(columnSearch)
+    );
+    
+    if (stateChanged) {
+      setPage(urlState.page);
+      setSortBy(urlState.sortBy);
+      setSortOrder(urlState.sortOrder);
+      setSearch(urlState.search);
+      setStatusFilter(urlState.statusFilter);
+      setLimit(urlState.limit);
+      setColumnSearch(urlState.columnSearch);
+    }
+  }, [location?.search, hasReactRouter, loadStateFromURL]);
 
   const handleStatusToggle = async (row) => {
     if (!toggleLink) return;

package/frontend/react-ui/hooks/index.js

@@ -14,3 +14,4 @@ export { useDebounce } from './useDebounce.js';
 export { useFocusTrap } from './useFocusTrap.js';
 export { useAnnouncer } from './useAnnouncer.js';
 export { useKeyboardNavigation } from './useKeyboardNavigation.js';
+export { useListNavigation } from './useListNavigation.js';

package/frontend/react-ui/hooks/useListNavigation.js

@@ -0,0 +1,75 @@
+import { useCallback, useEffect } from 'react';
+import { useNavigate, useLocation } from 'react-router-dom';
+
+/**
+ * Hook to preserve list page URL parameters when navigating to/from forms
+ * 
+ * For LIST pages: Automatically stores the current URL (with query params) whenever it changes
+ * For FORM pages: Provides functions to navigate back to the stored URL
+ * 
+ * @param {string} listPath - Base path of the list page (e.g., '/brands')
+ * @param {boolean} isListPage - Whether this is the list page (true) or form page (false)
+ * @returns {Object} - { navigateToList, getListUrl, storeCurrentUrl }
+ * 
+ * @example
+ * // In a list component
+ * useListNavigation('/brands', true); // Auto-stores URL on changes
+ * 
+ * // In a form component
+ * const { navigateToList, getListUrl } = useListNavigation('/brands', false);
+ * 
+ * // On save success or cancel
+ * navigateToList();
+ * 
+ * // In breadcrumb
+ * <BreadCrumb items={[
+ *   { label: 'Brands', to: getListUrl() }
+ * ]} />
+ */
+export function useListNavigation(listPath, isListPage = false) {
+  const navigate = useNavigate();
+  const location = useLocation();
+  
+  // Storage key for this list path
+  const storageKey = `listReturn_${listPath}`;
+  
+  /**
+   * Store current URL (called automatically on list pages)
+   */
+  const storeCurrentUrl = useCallback(() => {
+    const searchParams = location.search || '';
+    sessionStorage.setItem(storageKey, searchParams);
+  }, [location.search, storageKey]);
+  
+  /**
+   * Get the stored list URL with query params
+   * @returns {string} - Full URL with query params, or base path if none stored
+   */
+  const getListUrl = useCallback(() => {
+    const storedSearch = sessionStorage.getItem(storageKey);
+    return storedSearch ? `${listPath}${storedSearch}` : listPath;
+  }, [listPath, storageKey]);
+  
+  /**
+   * Navigate back to list page with preserved query params
+   */
+  const navigateToList = useCallback(() => {
+    const fullUrl = getListUrl();
+    navigate(fullUrl);
+    // Clear after navigation to prevent stale data
+    sessionStorage.removeItem(storageKey);
+  }, [navigate, getListUrl, storageKey]);
+  
+  // Auto-store URL on list pages whenever location changes
+  useEffect(() => {
+    if (isListPage && location.pathname === listPath) {
+      storeCurrentUrl();
+    }
+  }, [isListPage, location.pathname, location.search, listPath, storeCurrentUrl]);
+  
+  return {
+    navigateToList,
+    getListUrl,
+    storeCurrentUrl,
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vasuzex",
-  "version": "2.3.2",
+  "version": "2.3.4",
   "description": "Laravel-inspired framework for Node.js monorepos - V2 with optimized dependencies",
   "type": "module",
   "main": "./framework/index.js",