Debugging & Resolution Log

This document serves as a technical retrospective of the debugging phase and architectural refinements implemented during the Zlot dashboard development.

1. NUQS Architecture Failure (404/Missing Adapter)

• Issue: The application threw a runtime error: [nuqs] nuqs requires an adapter to work with your framework. and URL synchronization stopped working.
• Root Cause: nuqs (v2+) requires an explicit provider/adapter for the Next.js App Router to bridge the state between React components and the URL.
• Solution:
  • Updated app/layout.tsx.
  • Wrapped the application tree in NuqsAdapter from nuqs/adapters/next/app.
  • Placed it inside the QueryProvider to ensure clean hydration.

2. Sidebar Navigation Logic Regression

• Issue: After refactoring the sidebar to support grouped categories (Operations, Intelligence, etc.), the "Active" state for navigation links broke, and ESlint reported unused pathname variables.
• Root Cause: The grouping logic (using .reduce()) inadvertently stripped out the isActive utility function and its associated logic during the mapping phase.
• Solution:
  • Restored the isActive helper function.
  • Re-integrated usePathname for real-time URI matching.
  • Implemented a nested mapping strategy to render group headers without losing individual item functionality.

3. Duplicate Export Collision

• Issue: Next.js build failed due to multiple default exports in app/dashboard/parking/entry/page.tsx and app/dashboard/parking/active/page.tsx.
• Root Cause: During the transition from static placeholders to dynamic server components, boilerplate code was accidentally duplicated.
• Solution:
  • Audited page files and consolidated the logic into a single default export.
  • Serialized BigInt data types (database IDs) into strings during the fetch phase to prevent hydration errors.

4. Icon Registry Mismatches

• Issue: Multiple components were showing "Icon not found" or triggering linting warnings regarding missing imports from @phosphor-icons/react.
• Root Cause: Shift from dist/ssr to standard imports and missing icon names in the bundle across separate table components.
• Solution:
  • Standardized icons across UsersTable, VehiclesTable, and HistoryTable.
  • Swapped custom SVG wrappers for official Phosphor components for design consistency.

5. Analytics UI Hydration (Charts)

• Issue: Analytics page remained static with placeholder text despite recharts being in the dependencies.
• Root Cause: Chart components were not marked with "use client", causing server-side rendering failures for browser-specific APIs (DOM measurements).
• Solution:
  • Created a dedicated charts.tsx with the "use client" directive.
  • Implemented responsive containers to handle the "Industrial-Eco" layout's fluid grid.

6. Type Safety & Non-Null Assertions

• Issue: Frequent linting errors regarding any types and potential null pointers in transaction lookups.
• Root Cause: Direct database row mapping to UI didn't account for optional fields like exitTime or totalCost.
• Solution:
  • Defined strict TypeScript interfaces for Transaction, Vehicle, and Area.
  • Implemented proper null-checking and provided defaults (e.g., ₱0.00) in the HistoryTable cells.

7. Framer-Motion Invisible Rows (Animation Bug)

• Issue: Table rows would become completely invisible after a data mutation (e.g., deleting a record or adding a new one) until a manual page refresh.
• Root Cause: motion.tbody used a stagger animation that only triggered on the initial mount. router.refresh() updated the data but didn't trigger a re-mount, leaving new rows with opacity: 0.
• Solution:
  • Implemented a data-dependent key on motion.tbody (e.g., key={table.getRowModel().rows.map(r => r.id).join()}).
  • This forces a component re-mount on any data change, re-triggering the entrance animations cleanly.

8. Areas Module Performance & Browser Freezing

• Issue: The browser would hang or become unresponsive when clicking "Add Zone" or typing in the filter input.
• Root Cause: Infinite re-render loop triggered by an unstable routing object in TanStack Table's state and a lack of memoization for table columns/handlers.
• Solution:
  • Memoized the sorting state using useMemo.
  • Wrapped columns and all action handlers (handleEdit, handleSave) in useMemo and useCallback.
  • Stabilized the useReactTable hook to comply with React Compiler (Forget) optimization patterns.

9. Synchronous Filtering & Sorting State

• Issue: Filtering and sorting worked in the URL (URL updated) but the table content remained unchanged.
• Root Cause: getFilteredRowModel and getSortedRowModel were missing from the TanStack Table configuration, preventing the UI from reacting to the URL state.
• Solution:
  • Integrated full TanStack Table models for filtering and sorting.
  • Tied globalFilter directly to the nuqs search state.
  • Implemented client-side filtering for immediate feedback in the AreasManager and HistoryTable.