[BYOC] [Bulk Card Assignments] Release 1+2

contributingGuides/TABLE.md

@@ -0,0 +1,249 @@
+# Table Component
+
+A composable, generic table component with built-in filtering, search, and sorting capabilities.
+
+## Quick Start
+
+```tsx
+import Table from '@components/Table';
+import type { TableColumn, CompareItemsCallback } from '@components/Table';
+
+type Item = { id: string; name: string; status: string };
+type ColumnKey = 'name' | 'status';
+
+const columns: Array<TableColumn<ColumnKey>> = [
+  { key: 'name', label: 'Name' },
+  { key: 'status', label: 'Status' },
+];
+
+function MyTable() {
+  return (
+    <Table<Item, ColumnKey>
+      data={items}
+      columns={columns}
+      renderItem={({ item }) => <ItemRow item={item} />}
+      keyExtractor={(item) => item.id}
+    >
+      <Table.Header />
+      <Table.Body />
+    </Table>
+  );
+}
+```
+
+## Compositional Pattern
+
+The Table uses a **compound component pattern** where the parent `<Table>` manages all state and child components render specific UI parts:
+
+| Component | Purpose |
+|-----------|---------|
+| `<Table>` | Parent container that manages state and provides context |
+| `<Table.Header>` | Renders sortable column headers |
+| `<Table.Body>` | Renders data rows using FlashList |
+| `<Table.SearchBar>` | Search input that filters data |
+| `<Table.FilterButtons>` | Dropdown filter buttons |
+
+### Flexible Composition
+
+You only include the components you need:
+
+```tsx
+// Minimal: just data rows
+<Table data={items} columns={columns} renderItem={renderItem}>
+  <Table.Body />
+</Table>
+
+// With search
+<Table data={items} columns={columns} renderItem={renderItem} isItemInSearch={searchFn}>
+  <Table.SearchBar />
+  <Table.Body />
+</Table>
+
+// Full featured
+<Table
+  data={items}
+  columns={columns}
+  renderItem={renderItem}
+  isItemInSearch={searchFn}
+  isItemInFilter={filterFn}
+  compareItems={compareFn}
+  filters={filterConfig}
+>
+  <Table.SearchBar />
+  <Table.FilterButtons />
+  <Table.Header />
+  <Table.Body />
+</Table>
+```
+
+## Features
+
+### Sorting
+
+Enable by providing `compareItems`:
+
+```tsx
+const compareItems: CompareItemsCallback<Item, ColumnKey> = (a, b, { columnKey, order }) => {
+  const multiplier = order === 'asc' ? 1 : -1;
+  return a[columnKey].localeCompare(b[columnKey]) * multiplier;
+};
+
+<Table
+  data={items}
+  columns={columns}
+  renderItem={renderItem}
+  compareItems={compareItems}
+>
+  <Table.Header /> {/* Clicking headers toggles sort */}
+  <Table.Body />
+</Table>
+```
+
+Header click behavior: `ascending → descending → reset`
+
+### Searching
+
+Enable by providing `isItemInSearch`:
+
+```tsx
+const isItemInSearch = (item: Item, searchString: string) =>
+  item.name.toLowerCase().includes(searchString.toLowerCase());
+
+<Table
+  data={items}
+  columns={columns}
+  renderItem={renderItem}
+  isItemInSearch={isItemInSearch}
+>
+  <Table.SearchBar />
+  <Table.Body />
+</Table>
+```
+
+### Filtering
+
+Enable by providing `filters` config and `isItemInFilter`:
+
+```tsx
+import type { FilterConfig, IsItemInFilterCallback } from '@components/Table';
+
+const filterConfig: FilterConfig = {
+  status: {
+    filterType: 'single-select', // or 'multi-select'
+    options: [
+      { label: 'All', value: 'all' },
+      { label: 'Active', value: 'active' },
+      { label: 'Inactive', value: 'inactive' },
+    ],
+    default: 'all',
+  },
+};
+
+const isItemInFilter: IsItemInFilterCallback<Item> = (item, filterValues) => {
+  if (filterValues.includes('all')) return true;
+  return filterValues.includes(item.status);
+};
+
+<Table
+  data={items}
+  columns={columns}
+  renderItem={renderItem}
+  filters={filterConfig}
+  isItemInFilter={isItemInFilter}
+>
+  <Table.FilterButtons />
+  <Table.Body />
+</Table>
+```
+
+## Programmatic Control
+
+Access table methods via ref:
+
+```tsx
+import type { TableHandle } from '@components/Table';
+
+const tableRef = useRef<TableHandle<Item, ColumnKey>>(null);
+
+// Update sorting programmatically
+tableRef.current?.updateSorting({ columnKey: 'name', order: 'desc' });
+
+// Update search
+tableRef.current?.updateSearchString('query');
+
+// Get current state
+const sorting = tableRef.current?.getActiveSorting();
+const searchString = tableRef.current?.getActiveSearchString();
+
+// FlashList methods also available
+tableRef.current?.scrollToIndex({ index: 0 });
+
+<Table ref={tableRef} {...props}>
+  <Table.Body />
+</Table>
+```
+
+## Type Parameters
+
+| Parameter | Description |
+|-----------|-------------|
+| `T` | Type of items in the data array |
+| `ColumnKey` | String literal union of column keys (e.g., `'name' \| 'status'`) |
+| `FilterKey` | String literal union of filter keys |
+
+## Architecture
+
+### Middleware Pipeline
+
+Data processing flows through three middlewares:
+
+```
+data → [Filtering] → [Searching] → [Sorting] → processedData
+```
+
+Each middleware transforms the data array. The order is fixed: filters first, then search, then sort.
+
+### Context
+
+All sub-components access shared state via `TableContext`. You can create custom sub-components using `useTableContext`:
+
+```tsx
+import { useTableContext } from '@components/Table/TableContext';
+
+function CustomComponent<T>() {
+  const { processedData, activeSorting, updateSorting } = useTableContext<T>();
+  // Build custom UI using context data...
+}
+```
+
+## Column Configuration
+
+```tsx
+type TableColumn<ColumnKey> = {
+  key: ColumnKey;        // Unique identifier
+  label: string;         // Display text
+  styling?: {
+    flex?: number;              // Column width ratio
+    containerStyles?: StyleProp<ViewStyle>;
+    labelStyles?: StyleProp<TextStyle>;
+  };
+};
+```
+
+## Props Reference
+
+### Table Props
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `data` | `T[]` | Yes | Array of items to display |
+| `columns` | `TableColumn<ColumnKey>[]` | Yes | Column configuration |
+| `renderItem` | FlashList's `renderItem` | Yes | Row renderer |
+| `keyExtractor` | FlashList's `keyExtractor` | Yes | Unique key generator |
+| `compareItems` | `CompareItemsCallback<T, ColumnKey>` | No | Sorting comparator |
+| `isItemInSearch` | `IsItemInSearchCallback<T>` | No | Search predicate |
+| `isItemInFilter` | `IsItemInFilterCallback<T>` | No | Filter predicate |
+| `filters` | `FilterConfig<FilterKey>` | No | Filter dropdown config |
+| `ref` | `Ref<TableHandle<T, ColumnKey, FilterKey>>` | No | Ref for programmatic control |
+
+Plus all FlashList props except `data`.

src/CONST/index.ts

@@ -3437,6 +3437,7 @@ const CONST = {
             CSV: 'ccupload',
         },
         FEED_KEY_SEPARATOR: '#',
+        CARD_NUMBER_MASK_CHAR: 'X',
         STEP_NAMES: ['1', '2', '3', '4'],
         STEP: {
             BANK_CONNECTION: 'BankConnection',

src/ONYXKEYS.ts

@@ -706,6 +706,9 @@ const ONYXKEYS = {
          */
         WORKSPACE_CARDS_LIST: 'cards_',
 
+        /** Collection of objects where each object represents the card assignment that failed because we can't store errors in cardList or card feed due to server-provided IDs that aren't optimistic. */
+        FAILED_COMPANY_CARDS_ASSIGNMENTS: 'failedCompanyCardsAssignments_',
+
         /** Expensify cards settings */
         PRIVATE_EXPENSIFY_CARD_SETTINGS: 'private_expensifyCardSettings_',
 
@@ -1130,6 +1133,7 @@ type OnyxCollectionValuesMapping = {
     [ONYXKEYS.COLLECTION.EXPENSIFY_CARD_BANK_ACCOUNT_METADATA]: OnyxTypes.ExpensifyCardBankAccountMetadata;
     [ONYXKEYS.COLLECTION.PRIVATE_EXPENSIFY_CARD_MANUAL_BILLING]: boolean;
     [ONYXKEYS.COLLECTION.WORKSPACE_CARDS_LIST]: OnyxTypes.WorkspaceCardsList;
+    [ONYXKEYS.COLLECTION.FAILED_COMPANY_CARDS_ASSIGNMENTS]: OnyxTypes.FailedCompanyCardAssignments;
     [ONYXKEYS.COLLECTION.EXPENSIFY_CARD_CONTINUOUS_RECONCILIATION_CONNECTION]: OnyxTypes.PolicyConnectionName;
     [ONYXKEYS.COLLECTION.EXPENSIFY_CARD_USE_CONTINUOUS_RECONCILIATION]: OnyxTypes.CardContinuousReconciliation;
     [ONYXKEYS.COLLECTION.LAST_SELECTED_FEED]: OnyxTypes.CompanyCardFeedWithDomainID;

src/ROUTES.ts

@@ -16,10 +16,17 @@ import type {ReimbursementAccountStepToOpen} from './libs/ReimbursementAccountUt
 import {getUrlWithParams} from './libs/Url';
 import SCREENS from './SCREENS';
 import type {Screen} from './SCREENS';
+import type {CompanyCardFeedWithDomainID} from './types/onyx';
 import type {ConnectionName, SageIntacctMappingName} from './types/onyx/Policy';
 import type {CustomFieldType} from './types/onyx/PolicyEmployee';
 import type AssertTypesNotEqual from './types/utils/AssertTypesNotEqual';
 
+type WorkspaceCompanyCardsAssignCardParams = {
+    policyID: string;
+    feed: CompanyCardFeedWithDomainID;
+    cardID: string;
+};
+
 // This is a file containing constants for all the routes we want to be able to go to
 
 /**
@@ -2160,14 +2167,14 @@ const ROUTES = {
         },
     },
     WORKSPACE_COMPANY_CARDS_BANK_CONNECTION: {
-        route: 'workspaces/:policyID/company-cards/:bankName/bank-connection',
-        getRoute: (policyID: string | undefined, bankName: string, backTo: string) => {
+        route: 'workspaces/:policyID/company-cards/:feed/bank-connection',
+        getRoute: (policyID: string | undefined, feed: CompanyCardFeedWithDomainID, backTo?: string) => {
             if (!policyID) {
                 Log.warn('Invalid policyID is used to build the WORKSPACE_COMPANY_CARDS_BANK_CONNECTION route');
             }
 
             // eslint-disable-next-line no-restricted-syntax -- Legacy route generation
-            return getUrlWithBackToParam(`workspaces/${policyID}/company-cards/${bankName}/bank-connection`, backTo);
+            return getUrlWithBackToParam(`workspaces/${policyID}/company-cards/${feed}/bank-connection`, backTo);
         },
     },
     WORKSPACE_COMPANY_CARDS_ADD_NEW: {
@@ -2180,21 +2187,53 @@ const ROUTES = {
         route: 'workspaces/:policyID/company-cards/select-feed',
         getRoute: (policyID: string) => `workspaces/${policyID}/company-cards/select-feed` as const,
     },
-    WORKSPACE_COMPANY_CARDS_ASSIGN_CARD: {
-        route: 'workspaces/:policyID/company-cards/:feed/assign-card',
-
-        // eslint-disable-next-line no-restricted-syntax -- Legacy route generation
-        getRoute: (policyID: string, feed: string, backTo?: string) => getUrlWithBackToParam(`workspaces/${policyID}/company-cards/${encodeURIComponent(feed)}/assign-card`, backTo),
+    WORKSPACE_COMPANY_CARDS_BROKEN_CARD_FEED_CONNECTION: {
+        route: 'workspaces/:policyID/company-cards/:feed/broken-card-feed-connection',
+        getRoute: (policyID: string, feed: CompanyCardFeedWithDomainID) => `workspaces/${policyID}/company-cards/${encodeURIComponent(feed)}/broken-card-feed-connection` as const,
+    },
+    WORKSPACE_COMPANY_CARDS_ASSIGN_CARD_ASSIGNEE: {
+        route: 'workspaces/:policyID/company-cards/:feed/assign-card/:cardID/assignee',
+        getRoute: (params: WorkspaceCompanyCardsAssignCardParams, backTo?: string) =>
+            // eslint-disable-next-line no-restricted-syntax -- Legacy route generation
+            getUrlWithBackToParam(`workspaces/${params.policyID}/company-cards/${encodeURIComponent(params.feed)}/assign-card/${encodeURIComponent(params.cardID)}/assignee`, backTo),
+    },
+    WORKSPACE_COMPANY_CARDS_ASSIGN_CARD_CARD_SELECTION: {
+        route: 'workspaces/:policyID/company-cards/:feed/assign-card/:cardID/card-selection',
+        getRoute: (params: WorkspaceCompanyCardsAssignCardParams) =>
+            `workspaces/${params.policyID}/company-cards/${encodeURIComponent(params.feed)}/assign-card/${encodeURIComponent(params.cardID)}/card-selection` as const,
+    },
+    WORKSPACE_COMPANY_CARDS_ASSIGN_CARD_TRANSACTION_START_DATE: {
+        route: 'workspaces/:policyID/company-cards/:feed/assign-card/:cardID/transaction-start-date',
+        getRoute: (params: WorkspaceCompanyCardsAssignCardParams) =>
+            `workspaces/${params.policyID}/company-cards/${encodeURIComponent(params.feed)}/assign-card/${encodeURIComponent(params.cardID)}/transaction-start-date` as const,
+    },
+    WORKSPACE_COMPANY_CARDS_ASSIGN_CARD_CARD_NAME: {
+        route: 'workspaces/:policyID/company-cards/:feed/assign-card/:cardID/card-name',
+        getRoute: (params: WorkspaceCompanyCardsAssignCardParams) =>
+            `workspaces/${params.policyID}/company-cards/${encodeURIComponent(params.feed)}/assign-card/${encodeURIComponent(params.cardID)}/card-name` as const,
+    },
+    WORKSPACE_COMPANY_CARDS_ASSIGN_CARD_CONFIRMATION: {
+        route: 'workspaces/:policyID/company-cards/:feed/assign-card/:cardID/confirmation',
+        getRoute: (params: WorkspaceCompanyCardsAssignCardParams, backTo?: string) =>
+            // eslint-disable-next-line no-restricted-syntax -- Legacy route generation
+            getUrlWithBackToParam(`workspaces/${params.policyID}/company-cards/${encodeURIComponent(params.feed)}/assign-card/${encodeURIComponent(params.cardID)}/confirmation`, backTo),
+    },
+    WORKSPACE_COMPANY_CARDS_ASSIGN_CARD_INVITE_NEW_MEMBER: {
+        route: 'workspaces/:policyID/company-cards/:feed/assign-card/:cardID/invite-new-member',
+        getRoute: (params: WorkspaceCompanyCardsAssignCardParams) =>
+            `workspaces/${params.policyID}/company-cards/${encodeURIComponent(params.feed)}/assign-card/${encodeURIComponent(params.cardID)}/invite-new-member` as const,
     },
     WORKSPACE_COMPANY_CARD_DETAILS: {
-        route: 'workspaces/:policyID/company-cards/:bank/:cardID',
+        route: 'workspaces/:policyID/company-cards/:feed/:cardID',
 
-        // eslint-disable-next-line no-restricted-syntax -- Legacy route generation
-        getRoute: (policyID: string, cardID: string, bank: string, backTo?: string) => getUrlWithBackToParam(`workspaces/${policyID}/company-cards/${bank}/${cardID}`, backTo),
+        getRoute: (policyID: string, feed: CompanyCardFeedWithDomainID, cardID: string, backTo?: string) =>
+            // eslint-disable-next-line no-restricted-syntax -- Legacy route generation
+            getUrlWithBackToParam(`workspaces/${policyID}/company-cards/${encodeURIComponent(feed)}/${encodeURIComponent(cardID)}`, backTo),
     },
-    WORKSPACE_COMPANY_CARD_NAME: {
-        route: 'workspaces/:policyID/company-cards/:bank/:cardID/edit/name',
-        getRoute: (policyID: string, cardID: string, bank: string) => `workspaces/${policyID}/company-cards/${bank}/${cardID}/edit/name` as const,
+    WORKSPACE_COMPANY_CARD_EDIT_CARD_NAME: {
+        route: 'workspaces/:policyID/company-cards/:feed/:cardID/edit/name',
+        getRoute: (policyID: string, cardID: string, feed: CompanyCardFeedWithDomainID) =>
+            `workspaces/${policyID}/company-cards/${encodeURIComponent(feed)}/${encodeURIComponent(cardID)}/edit/name` as const,
     },
     WORKSPACE_COMPANY_CARD_EXPORT: {
         route: 'workspaces/:policyID/company-cards/:bank/:cardID/edit/export',