Customer Management: Complete Dashboard Guide

BSTD's Customer Management module provides a centralized, powerful dashboard to view, organize, and maintain all your customer data and linked logistics documents. This comprehensive guide covers every feature, interaction, and workflow available in the customer table.

From cross-field search across customer and quotation data, linking 9 different document types, instant PDF viewing with zero caching, secure token-based sharing, and smart viewport-aware dropdowns — this page documents everything you need to master your customer operations.

Customer Table & Cards

The dashboard displays customers in two responsive layouts: a detailed table for desktop and compact cards for mobile. Both views show the same rich information organized for optimal scanning.

Desktop Table Columns

• # (Index): Sequential row number for easy reference.
• Customer:Displays the customer's party name (from linked quotation), a colored avatar with the first initial, customer ID, and clickable phone number.
• Route: Shows origin city and destination city with a directional arrow, plus the creation date formatted via formatDate.
• Docs:A badge showing the count of linked documents out of 9 total possible types (e.g., "3/9"). Click to open the Link Docs modal.
• Actions: A three-dot menu button that opens the comprehensive action dropdown.

Mobile Card Layout

On mobile devices (below the md breakpoint), the table transforms into stacked cards. Each card shows:

• Customer avatar with initial, party name, customer ID, and phone number
• Route (origin → destination) with document count badge
• Creation date and the three-dot action menu

Customer Information Display

• Avatar: A rounded square avatar with the first letter of the party name, using theme-aware background colors (gray-100 in light, gray-800 in dark).
• Party Name:The primary customer name from the linked quotation. If no quotation is linked, displays "N/A".
• Customer ID: The unique internal identifier for the customer record.
• Phone Link:The customer's mobile number is a clickable tel:link that opens your device's calling application.
• Route Colors: Origin city is styled with success text color (green), destination with danger text color (red), making the direction visually intuitive.

Advanced Cross-Field Search

The search bar is one of the most powerful features of the Customer Management module. It searches across both customer data and linked quotation data simultaneously.

Search Scope

The search scans the following fields in real-time:

• Real-time Filtering: Results update instantly as you type. No need to press Enter or click a search button.
• Case-insensitive: Searches are case-insensitive and trim whitespace automatically.
• Quotation Cross-search: You can search for a vehicle number, driver name, or destination city and find the associated customer even if that data is stored in the quotation, not the customer record.
• Clear Button:When a search query is active, a "Clear" button appears to instantly reset the filter and show all customers.
• Result Count:The header displays the total number of entries currently visible (e.g., "47 entries").

Document Linking System

The document linking system is the core of the Customer Management module. It allows you to associate up to 9 different logistics document types with each customer, creating a centralized document repository.

Linked Document Badge

Each customer row displays a pill-shaped badge showing the count of linked documents (e.g., "3/9"). The badge styling changes based on linkage status:

• Linked (≥1): Uses the brand theme background color, indicating active document associations.
• Unlinked (0): Uses a neutral gray background, indicating no documents have been linked yet.
• Click to Link: Clicking the badge opens the LinkDocsModal where you can associate documents.

Link Docs Modal

The Link Docs modal provides an interface to connect existing documents to a customer profile. It accepts the customer ID and pre-populates with any existing linked data.

• Pre-populated Data: If documents are already linked, the modal loads them automatically for editing.
• Success Feedback:After successful linking, a green success toast appears ("Documents linked successfully") and the parent data refreshes via the onLinkDocsSuccess callback.
• Company Theme:The modal inherits the company's theme colors for consistent branding.

Document Number Storage

Each document type stores its unique number in the customer record:

9 Document Types Supported

BSTD supports linking and managing 9 distinct logistics document types. Each type has its own page route, API endpoint, and document number field.

Edit vs. Create Workflow

From the dropdown menu, each document type provides smart routing:

• Edit Existing: If a document number exists for that type, the link opens the document editor in edit mode (e.g., /v1/lr?edit=LR-2024-001).
• Create New:If no document is linked, the link opens the document creator pre-filled with the customer's quotation number (e.g., /v1/lr?quotation=QT-2024-001).
• Visual Indicators:Each document row in the dropdown shows a pencil icon and clearly labels whether you're editing an existing document or creating a new one.

Instant PDF Viewer

For any linked document, you can instantly view its PDF without navigating away from the customer dashboard. The PDF viewer is optimized for zero caching and memory leak prevention.

PDF Generation

• No Cache: Every PDF request appends a cache-busting query parameter (_cb=timestamp) to ensure you always see the latest version.
• Blob URL Lifecycle: PDFs are fetched as blobs, converted to temporary object URLs, opened in a new tab, and automatically revoked after 8 seconds to prevent memory leaks.
• Popup Blocker Safe: PDFs open via a hidden anchor element with target="_blank" andrel="noopener noreferrer", avoiding popup blocker issues and double-window problems.
• Debounced Clicks: A 1.2-second lock prevents accidental double-clicks from generating duplicate PDF requests.

Supported PDF Types

The PDF viewer supports all 9 document types through dedicated API endpoints:

• LR PDF — Generated via api.lr.generatePdf(docId, "consignor", cacheBuster)
• Tax Invoice PDF — api.invoices.generatePdf(docId, cacheBuster)
• Vehicle Condition PDF — api.vc.generatePdf(docId, cacheBuster)
• Packing List PDF — api.gr.generatePdf(docId, cacheBuster)
• Money Receipt PDF — api.mr.generatePdf(docId, cacheBuster)
• FOV PDF — api.fov.generatePdf(docId, cacheBuster)
• NOC PDF — api.noc.generatePdf(docId, cacheBuster)
• TWS PDF — api.tws.generatePdf(docId, cacheBuster)

Smart Action Dropdown Menu

The three-dot menu button on each customer row opens a comprehensive, fixed-position dropdown menu with viewport-aware positioning. This is one of the most sophisticated UI components in the dashboard.

Menu Sections

Viewport-Aware Positioning

The dropdown uses a sophisticated positioning algorithm that measures the actual rendered content height and calculates the best position to avoid clipping:

• Height Measurement: UsesuseLayoutEffect to measure the actual rendered dropdown height immediately upon opening.
• Below Placement:If sufficient space exists below the trigger button, the dropdown aligns its right edge with the trigger's right edge and opens downward.
• Above Flip: If space below is insufficient but space above exists, the dropdown flips to open above the trigger.
• Best-Fit Fallback: If neither direction has enough space, the dropdown positions in the direction with more available space and clamps to viewport edges with 8px margins.
• Horizontal Safety: The dropdown never extends beyond the left or right viewport edges, with automatic left-edge alignment fallback.

Auto-Close Behavior

• Outside Click: Clicking anywhere outside the dropdown (detected via data-dropdown attribute) closes the menu.
• Scroll Close: Scrolling the page automatically closes the dropdown to prevent misalignment.
• Resize Close: Window resizing closes the dropdown to recalculate positioning.
• Toggle Logic:Clicking the same three-dot button again closes the dropdown; clicking a different row's button switches the open menu.

Secure Document Sharing

The Share feature allows you to generate secure, token-based links for sharing customer documents with clients via WhatsApp, email, or any messaging platform.

Share Modal

• Customer ID: The modal is scoped to the selected customer, ensuring only their documents are included in the share.
• Customer Phone:The customer's phone number (from the linked quotation) is passed to the modal for pre-filling sharing options.
• Token-Based Security: Generated links use encrypted tokens to ensure secure, time-limited access. Links expire automatically and cannot be accessed without the proper token.
• WhatsApp Integration: The modal supports direct WhatsApp sharing with automatic message formatting.
• Company Theme:The Share Modal inherits the company's theme colors for consistent branding.

Deleting Customers

Customer deletion is protected by multiple safeguards to prevent accidental data loss.

Delete Flow

1. Click Delete: From the dropdown menu, select Delete. The menu closes immediately.
2. Confirmation Modal:A styled modal appears (not a native browser alert) with a red warning icon, the customer's party name prominently displayed, and a clear warning that the action cannot be undone.
3. Cancel Option: Clicking Cancel, the backdrop, or the X button safely dismisses the modal without any deletion.
4. Confirm Delete: Clicking the red Delete button triggers the onDelete callback, which makes a single API call to remove the customer.
5. Toast Feedback:After deletion, a success toast appears ("Customer deleted successfully"). If the API call fails, an error toast displays the error message.

Delete Confirmation Modal Design

• Red Warning Icon: A circular red background with a trash icon visually signals the destructive nature.
• Customer Name Display: The party name (or customer ID as fallback) is shown in bold to confirm the target.
• Theme-aware Styling:The modal uses the current theme's card background, border, and text colors for consistent appearance.

Infinite Scroll Pagination

The customer list uses infinite scroll pagination to handle large datasets efficiently without overwhelming the browser or the user.

How It Works

• Batch Size: Initially loads 10 customers. As you scroll, additional batches of 10 are loaded automatically.
• Sorting: Customers are sorted by creation date in descending order (newest first) before pagination is applied.
• Loading Indicator:When fetching the next batch, a spinning loader with "Loading more..." text appears at the bottom of the list.
• Search Compatibility: Infinite scroll works seamlessly with search filtering — only filtered results are paginated.
• Hook-based: Powered by theuseInfiniteScroll custom hook for clean, reusable logic.

Responsive Design

The Customer Management module is fully responsive, adapting its layout from mobile phones to large desktop monitors.

Layout Breakpoints

• Table Overflow: The desktop table supports horizontal scrolling via overflow-x-auto for narrow viewports that still meet the desktop breakpoint.
• Touch Targets: All interactive elements (buttons, dropdown triggers) maintain adequate touch target sizes for mobile usability.
• Text Truncation: Long party names are truncated with truncate and min-w-0classes to prevent layout breaking.

Dark Mode & Theme Support

The entire Customer Management module adapts seamlessly to both light and dark themes through the useThemeColors hook.

• Dynamic Colors: All backgrounds, borders, text, and input colors are determined by the theme hook and update instantly when the system theme changes.
• Avatar Backgrounds: Customer avatars use gray-100 in light mode and gray-800in dark mode for optimal contrast.
• Table Hover: Row hover states use theme-aware colors for subtle highlighting without jarring transitions.
• Dropdown Styling: The fixed dropdown menu inherits card background, border, and text colors from the active theme.
• Company Theme Override: If a company has a custom theme configured, it is passed to all child components (modals, dropdowns, toasts) for brand consistency.