ClientListing

ClientListing

The ClientListing component provides a specialized implementation of DistrictSelection for displaying and selecting forest clients from the authenticated user's client list. It fetches client data based on the user's permissions and presents them in a searchable, selectable list.

Props

This component does not accept any props. It is a self-contained implementation that manages its own data fetching and state.

Usage

import ClientListing from '@/components/core/DistrictSelection/ClientListing';

// Simple usage - no props needed
<ClientListing />

Features

Authenticated Client Access

The component uses the useAuth hook to retrieve the list of client numbers the current user has access to via getClients(). This ensures users only see clients they have permission to view.

Data Fetching

Uses React Query to fetch client details from the Forest Client API:

const { data, isLoading } = useQuery({
  queryKey: ['forest-clients', 'search', getClients()],
  queryFn: () => APIs.forestclient.searchByClientNumbers(
    getClients(),
    0,
    getClients().length
  ),
  enabled: !!getClients().length,
  select: (data) =>
    data.map((client) => ({
      id: client.clientNumber,
      name: client.name ?? client.clientName,
      kind: client.clientTypeCode?.code,
    })),
});

Data Transformation

Raw client data is transformed to match the DistrictType interface:

• id: Maps to client.clientNumber
• name: Uses client.name with fallback to client.clientName
• kind: Maps to client.clientTypeCode.code (used for icon display)

Search Functionality

Implements a simple filter function that searches across:

• Client name (case-insensitive)
• Client ID/number (case-insensitive, exact match)

const filter = (client: DistrictType, keyword: string): boolean => {
  return (
    client.name.trim().toLowerCase().includes(keyword.toLowerCase()) ||
    client.id.trim().toLowerCase() === keyword.toLowerCase()
  );
};

Preference Persistence

Selected clients are stored in user preferences under the key selectedClient, allowing the selection to persist across sessions.

Configuration

The component configures DistrictSelection with:

Configuration	Value	Purpose
preferenceKey	"selectedClient"	Key for storing selected client in preferences
deselectLabel	"Select no client"	Label for the deselect option
searchLabel	"Search by client name or ID"	Placeholder text for the search input

Client Type Codes

The component supports the following client type codes (mapped to icons via ClientTypeIconMap):

• A: Association (Partnership icon)
• B: First Nation Band (EventsAlt icon)
• C: Corporation (Building icon)
• F: Ministry of Forests and Range (Tree icon)
• G: Government (Finance icon)
• I: Individual (UserAvatar icon)
• L: Limited Partnership (Group icon)
• P: General Partnership (Events icon)
• R: First Nation Group (EventsAlt icon)
• S: Society (GroupPresentation icon)
• T: First Nation Tribal Council (GroupPresentation icon)
• U: Unregistered Company (Enterprise icon)

Dependencies

Required Context Providers

• AuthProvider: Provides getClients() method for accessing user's client list
• PreferenceProvider: Manages storage and retrieval of selected client
• QueryClientProvider: Required for React Query functionality

API Services

• APIs.forestclient.searchByClientNumbers: Fetches detailed client information

Example Integration

import { AuthProvider } from '@/context/auth/AuthProvider';
import { PreferenceProvider } from '@/context/preference/PreferenceProvider';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import ClientListing from '@/components/core/DistrictSelection/ClientListing';

const queryClient = new QueryClient();

function MyApp() {
  return (
    <QueryClientProvider client={queryClient}>
      <AuthProvider>
        <PreferenceProvider>
          <ClientListing />
        </PreferenceProvider>
      </AuthProvider>
    </QueryClientProvider>
  );
}

Query Behavior

Enabled Condition

The query only executes when getClients().length > 0, preventing unnecessary API calls when the user has no accessible clients.

Cache Key

Uses a composite query key: ['forest-clients', 'search', getClients()]

This ensures the query refetches when the user's client list changes.

Stale Time

No explicit staleTime is set, so the query follows the default React Query behavior (data becomes stale immediately and refetches on mount/focus if cache is stale).

Accessing Selected Client

To retrieve the currently selected client in other components:

import { usePreference } from '@/context/preference/usePreference';

function MyComponent() {
  const { userPreference } = usePreference();
  const selectedClientId = userPreference.selectedClient;

  // Use selectedClientId to filter data, make requests, etc.
}

Best Practices

1. Ensure proper context wrapping: The component requires AuthProvider and PreferenceProvider to function
2. Handle loading states: The parent component should handle cases where clients are still loading
3. Consider error handling: Wrap usage in an ErrorBoundary to handle API failures gracefully
4. Verify user permissions: The component relies on getClients() returning accurate data

Related Components

• DistrictSelection: The base component that ClientListing extends
• DistrictItem: Renders individual client items in the list
• DistrictListing: Similar component for district selection

Notes

• If the user has no accessible clients, the component will display only the deselect option
• Client names are prioritized over client names from the API (client.name ?? client.clientName)
• The search is performed client-side, so all accessible clients must be loaded before filtering
• The component automatically hides the search bar if fewer than 5 clients are available