relay-infinite-scroll-select

name	relay-infinite-scroll-select
description	Create Relay-based infinite scroll select components extending BAISelect. Supports name-based values (usePaginationFragment) and id-based values (useLazyLoadQuery + useLazyPaginatedQuery) with search, optimistic updates, and multiple selection modes.

Relay Infinite Scroll Select Component Creator

Activation Triggers

• "Create a Relay infinite scroll select for [entity]"
• "Build a select with GraphQL pagination"
• "Add [Entity]Select component with infinite scroll"
• "Create a select component that fetches from GraphQL"

Quick Start Decision Tree

START: Does your select need dynamic query parameters?

┌─────────────────────────────────────────────────────────────┐
│ Q: Do you need dynamic control over query parameters?      │
│    (filter, limit, first, order, etc.)                     │
│    OR need external refetch capability?                    │
└─────────────────────────────────────────────────────────────┘
                         │
          ┌──────────────┴──────────────┐
          │                             │
         NO                            YES
          │                             │
          ▼                             ▼
   ┌─────────────┐             ┌─────────────┐
   │  Pattern A  │             │  Pattern B  │
   │  (Simple)   │             │ (Dynamic)   │
   └─────────────┘             └─────────────┘
          │                             │
          ▼                             ▼
Reference:                    References:
BAIAdminResourceGroupSelect   BAIUserSelect (email-based)
                              BAIVFolderSelect (id-based)

Pattern Comparison

Criteria	Pattern A (Simple)	Pattern B (Dynamic)
Value Type	String (name)	Any (name, email, id, row_id, etc.)
Relay Hook	usePaginationFragment	useLazyLoadQuery + useLazyPaginatedQuery
Queries	1 fragment	2 queries
Dynamic First	❌ Not needed	✅ Default (fetches all selected values)
Dynamic Parameters	❌ Limited	✅ Full control (filter, first, limit, order, etc.)
Multiple Mode	Single only	Full support
Global ID	Not needed	Can handle (if needed)
Optimistic UI	Not needed	Required
State Management	Simple	Complex
Ref Export	No	Yes (refetch support)
Complexity	🟢 ~100 lines	🟡 ~300-350 lines
Use Case	Simple, static requirements	Dynamic filters, external refetch, multiple props control

Pattern B Examples by Value Type

Example	Value Type	Special Features
BAIUserSelect	Email	Dynamic first, email filtering
BAIVFolderSelect	ID / row_id	Dynamic first, Global ID conversion, scope filtering
Custom Select	Name	Can use Pattern B even with name if dynamic control needed

Implementation Checklists

Pattern A Checklist (Name-Based Value)

Component Setup:

• Import usePaginationFragment from 'react-relay'
• Import BAISelect, TotalFooter, Skeleton
• Create props interface extending Omit<BAISelectProps, 'options' | 'labelInValue'>
• Add queryRef prop for fragment key

GraphQL Fragment:

graphql\`
  fragment YourComponent_fragment on Query
  @argumentDefinitions(
    first: { type: "Int", defaultValue: 10 }
    after: { type: "String" }
    filter: { type: "YourFilterType" }
  )
  @refetchable(queryName: "YourComponentPaginationQuery") {
    yourEntities(first: $first, after: $after, filter: $filter)
      @connection(key: "YourComponent_yourEntities") {
      count
      edges {
        node {
          id
          name
        }
      }
    }
  }
\`

Required Checklist:

• @argumentDefinitions (first, after, filter)
• @refetchable with unique queryName
• @connection with unique key
• count field for total
• Required fields (id, name)

BAISelect Integration:

• ref={selectRef} with useRef
• options from mapped edges
• searchAction with refetch() and scrollTo(0)
• showSearch with conditional handling (see showSearch Configuration section)
• endReached={() => hasNext && loadNext(10)}
• notFoundContent with Skeleton
• footer with TotalFooter

Pattern B Checklist (ID-Based Value)

Component Setup:

• Import useLazyLoadQuery, useDeferredValue, useTransition, useOptimistic
• Import useLazyPaginatedQuery, useFetchKey, useDebouncedDeferredValue custom hooks
• Import useControllableValue from 'ahooks'
• Import toLocalId, mergeFilterValues helpers
• Add 'use memo' directive

State Management:

• useControllableValue for value and open
• useDeferredValue for controllableValue, open, and fetchKey
• useState for searchStr and optimisticValueWithLabel
• useDebouncedDeferredValue for searchStr (debounce + defer query execution)
• useOptimistic for optimisticSearchStr (immediate UI feedback) - simple pattern without dispatcher
• useTransition for refetch
• useFetchKey for cache invalidation

GraphQL Queries:

Query 1 - Selected Values (with Dynamic First):

graphql\`
  query YourComponentValueQuery(
    $selectedFilter: String
    $first: Int!
    $skipSelected: Boolean!
  ) {
    yourEntities(filter: $selectedFilter, first: $first)
      @skip(if: $skipSelected) {
      edges {
        node {
          id
          row_id
          name
        }
      }
    }
  }
\`

// Variables
{
  selectedFilter: /* filter based on selected values */,
  first: _.castArray(deferredControllableValue).length, // 🔑 Dynamic
  skipSelected: _.isEmpty(deferredControllableValue),
}

Query 2 - Paginated Options:

graphql\`
  query YourComponentPaginatedQuery(
    $offset: Int!
    $limit: Int!
    $filter: String
  ) {
    yourEntities(
      offset: $offset
      first: $limit
      filter: $filter
      order: "-created_at"
    ) {
      count
      edges {
        node {
          id
          row_id
          name
        }
      }
    }
  }
\`

Query Checklist:

• ValueQuery with @skip directive
• ValueQuery with dynamic $first parameter (REQUIRED for Pattern B)
• PaginatedQuery with offset/limit
• selectedFilter uses toLocalId() for Global IDs (if using Global IDs)
• Both queries have required fields (id, name, or email)
• count field in PaginatedQuery
• Variables include first: _.castArray(value).length (REQUIRED for Pattern B)

Value-to-Label Mapping:

• Build controllableValueWithLabel from selected query
• Maintain selection order with _.castArray
• Filter out null edges
• Fallback to value as label when no data

Optimistic Updates:

• useOptimistic for optimisticSearchStr (search input feedback)
• useState for optimisticValueWithLabel (selection feedback)
• Switch between optimistic and real value based on deferred comparison
• Preserve labels in onChange (handle React element labels)

BAISelect Integration:

• labelInValue prop
• value with optimistic switching
• onChange with label preservation
• searchAction with setOptimisticSearchStr then setSearchStr (no transition wrapper needed)
• showSearch with conditional handling (see showSearch Configuration section)
• showSearch.searchValue set to optimisticSearchStr for immediate feedback
• endReached={() => loadNext()}
• labelRender/optionRender for custom display
• loading with four conditions: loading, value comparison, searchStr !== debouncedDeferredValue, isPendingRefetch

Ref Export:

• useImperativeHandle for refetch
• startRefetchTransition wrapper
• Export ref interface type

Common Patterns

showSearch Configuration

Both patterns should implement flexible showSearch handling to support:

1. Disabling search completely with showSearch={false}
2. Merging user-provided showSearch configurations
3. Using optimistic search strings for immediate feedback

Pattern A: Basic showSearch

// State (if not already present)
const [searchStr, setSearchStr] = useState<string>();
const [optimisticSearchStr, setOptimisticSearchStr] =
  useOptimistic(searchStr);

// In searchAction
searchAction={async (value) => {
  setOptimisticSearchStr(value);  // Immediate UI feedback
  setSearchStr(value);             // Actual state for query
  selectRef.current?.scrollTo(0);
  refetch({ filter: value ? { name: { contains: value } } : null });
  await selectProps.searchAction?.(value);
}}

// In BAISelect
showSearch={
  selectProps.showSearch === false
    ? false
    : {
        searchValue: optimisticSearchStr,
        autoClearSearchValue: true,
        filterOption: false,
        ...(_.isObject(selectProps.showSearch)
          ? _.omit(selectProps.showSearch, ['searchValue'])
          : {}),
      }
}

Pattern B: Advanced showSearch with debouncing

// State (already present in Pattern B)
const [searchStr, setSearchStr] = useState<string>();
const debouncedDeferredValue = useDebouncedDeferredValue(searchStr);
const [optimisticSearchStr, setOptimisticSearchStr] =
  useOptimistic(searchStr);

// In searchAction
searchAction={async (value) => {
  setOptimisticSearchStr(value);  // Immediate UI feedback
  setSearchStr(value);             // Actual state (will be debounced + deferred)
  await selectProps.searchAction?.(value);
}}

// In BAISelect
showSearch={
  selectProps.showSearch === false
    ? false
    : {
        searchValue: optimisticSearchStr,
        autoClearSearchValue: true,
        filterOption: false,
        ...(_.isObject(selectProps.showSearch)
          ? _.omit(selectProps.showSearch, ['searchValue'])
          : {}),
      }
}

Why this pattern?

• ✅ Flexibility: Parent can disable search with showSearch={false}
• ✅ Extensibility: Parent can provide custom showSearch config (except searchValue)
• ✅ Consistency: All relay select components follow the same pattern
• ✅ Optimistic UI: Uses optimisticSearchStr for immediate feedback
• ✅ Type Safety: TypeScript catches invalid configurations

Usage Examples:

// Disable search completely
<BAIUserSelect showSearch={false} />

// Custom showSearch configuration
<BAIUserSelect
  showSearch={{
    placeholder: "Search by email...",
    maxLength: 50,
  }}
/>

// Default behavior (search enabled)
<BAIUserSelect />

Common Pitfalls:

// ❌ Bad: Hardcoded showSearch object (not flexible)
showSearch={{
  autoClearSearchValue: true,
  filterOption: false,
}}

// ❌ Bad: No optimistic search (delayed feedback)
showSearch={{
  searchValue: searchStr,  // Use optimisticSearchStr instead
  autoClearSearchValue: true,
  filterOption: false,
}}

// ❌ Bad: Not checking showSearch === false
showSearch={{
  // Always shows search, can't be disabled
}}

// ✅ Good: Conditional with optimistic + merge
showSearch={
  selectProps.showSearch === false
    ? false
    : {
        searchValue: optimisticSearchStr,
        autoClearSearchValue: true,
        filterOption: false,
        ...(_.isObject(selectProps.showSearch)
          ? _.omit(selectProps.showSearch, ['searchValue'])
          : {}),
      }
}

Dynamic First Parameter (Default in Pattern B)

Pattern B always uses dynamic first parameter to ensure all selected values are fetched:

const { entity_nodes: selectedNodes } =
  useLazyLoadQuery<YourComponentValueQuery>(
    graphql`
      query YourComponentValueQuery(
        $selectedFilter: String
        $first: Int!
        $skipSelected: Boolean!
      ) {
        entity_nodes(filter: $selectedFilter, first: $first)
          @skip(if: $skipSelected) {
          edges {
            node {
              id
              name
            }
          }
        }
      }
    `,
    {
      selectedFilter: /* ... */,
      first: _.castArray(deferredControllableValue).length, // 🔑 Dynamic
      skipSelected: _.isEmpty(deferredControllableValue),
    },
  );

Why this is the default in Pattern B:

• ✅ Fetch exactly the number of selected items
• ✅ No over-fetching (performance)
• ✅ No under-fetching (data completeness)
• ✅ Works with any selection count (1, 10, 100, etc.)
• ✅ Essential for multiple selection mode
• ✅ Prevents data loss when users select many items

Without dynamic first (NOT Pattern B):

// ❌ Bad: Hardcoded limit (Pattern A approach, not suitable for Pattern B)
first: 10  // Fails if user selects 50 items

// ❌ Bad: No first parameter
// May return only default number of results (usually 10)

// ✅ Good: Pattern B always uses dynamic first
first: _.castArray(deferredControllableValue).length

Multiple Mode Support

// Check for empty value before casting to avoid issues with empty arrays
const valueArray = _.isEmpty(value) ? [] : _.castArray(value);

// Process each value uniformly
valueArray.map((value) => {
  // Process each value
});

Key Points:

• Use _.isEmpty() to check for empty value before casting
• _.castArray() ensures uniform handling of single and multiple modes
• Prevents issues when value is undefined or empty array

Search with Transitions

// Pattern A: Refetch with transition and optimistic search
const [searchStr, setSearchStr] = useState<string>();
const [optimisticSearchStr, setOptimisticSearchStr] =
  useOptimistic(searchStr);

searchAction={async (value) => {
  setOptimisticSearchStr(value);  // Immediate UI feedback
  setSearchStr(value);             // Actual state for query
  selectRef.current?.scrollTo(0);
  refetch({ filter: value ? { name: { contains: value } } : null });
  await selectProps.searchAction?.(value);
}}

// Conditional showSearch with user config merge
showSearch={
  selectProps.showSearch === false
    ? false
    : {
        searchValue: optimisticSearchStr,
        autoClearSearchValue: true,
        filterOption: false,
        ...(_.isObject(selectProps.showSearch)
          ? _.omit(selectProps.showSearch, ['searchValue'])
          : {}),
      }
}

// Pattern B: Optimistic search with useDebouncedDeferredValue
import useDebouncedDeferredValue from '../../helper/useDebouncedDeferredValue';

const [searchStr, setSearchStr] = useState<string>();
const debouncedDeferredValue = useDebouncedDeferredValue(searchStr);
const [optimisticSearchStr, setOptimisticSearchStr] =
  useOptimistic(searchStr);

// Use debouncedDeferredValue (debounced + deferred) in query filter
filter: mergeFilterValues([
  mergedFilter,
  debouncedDeferredValue ? `email ilike "%${debouncedDeferredValue}%"` : null,
])

// searchAction sets optimistic value immediately, then actual value
searchAction={async (value) => {
  setOptimisticSearchStr(value);  // Optimistic update for immediate UI feedback
  setSearchStr(value);             // Actual state (will be debounced + deferred)
  await selectProps.searchAction?.(value);
}}

// Conditional showSearch with user config merge
showSearch={
  selectProps.showSearch === false
    ? false
    : {
        searchValue: optimisticSearchStr,
        autoClearSearchValue: true,
        filterOption: false,
        ...(_.isObject(selectProps.showSearch)
          ? _.omit(selectProps.showSearch, ['searchValue'])
          : {}),
      }
}

// Show loading when search query is executing
loading={
  loading ||
  controllableValue !== deferredControllableValue ||
  searchStr !== debouncedDeferredValue ||  // Loading during debounce + defer
  isPendingRefetch
}

Why useDebouncedDeferredValue + useOptimistic for search?

• ✅ Input field shows optimistic value immediately (best UX)
• ✅ Debounce reduces query frequency during fast typing (200ms default)
• ✅ useDeferredValue prevents UI blocking during query execution
• ✅ Query uses debouncedDeferredValue (debounced + deferred state)
• ✅ Works seamlessly with BAISelect's built-in startTransition wrapper
• ✅ React automatically manages the complete state transition flow
• ✅ Loading indicator shows during debounce + defer period
• ✅ Best balance between responsiveness and performance
• ✅ Prevents excessive GraphQL queries during fast typing

Global ID Conversion

import { toLocalId, toGlobalId } from '../../helper';

// When filtering (valuePropName === 'id')
const filterValue = valuePropName === 'id' ? toLocalId(value) : value;

Filter Merging

import { mergeFilterValues } from '../BAIPropertyFilter';

const filter = mergeFilterValues([
  baseFilter,
  searchStr ? \`name ilike "%\${searchStr}%"\` : null,
  externalFilter,
], '&'); // Default operator

Controllable Props

const [value, setValue] = useControllableValue(props);
const [open, setOpen] = useControllableValue(props, {
  valuePropName: 'open',
  trigger: 'onOpenChange',
});

Pattern B: Dynamic Query Parameters

Core Capabilities

Pattern B (Dynamic) provides full control over GraphQL query parameters through props:

1. Dynamic First Parameter (Default Behavior)

// ALWAYS fetch all selected values in Pattern B
first: _.castArray(deferredControllableValue).length

This is not optional - it's the defining characteristic of Pattern B that ensures data completeness.

2. Dynamic Filter

// Combine multiple filters dynamically
filter={mergeFilterValues([
  'status == "ACTIVE"',
  searchStr ? `name ilike "%${searchStr}%"` : null,
  props.filter,  // External filter from props
])}

3. Dynamic Limit

// Control pagination size via props
{ limit: props.pageSize || 10 }

4. Dynamic Order

// Control sort order via props
order: props.sortBy || '-created_at'

5. External Refetch

// Expose refetch via ref
const selectRef = useRef<YourSelectRef>(null);
selectRef.current?.refetch();

When Pattern B is Essential

Even if your value is a simple name (not ID), use Pattern B when you need:

• ✅ Dynamic filter from parent component
• ✅ External refetch capability
• ✅ Control over fetchPolicy
• ✅ Multiple selection with optimistic updates
• ✅ Dynamic pagination size
• ✅ Custom sort order

Example: Name-based but needs Pattern B

// Even though value is 'name', we need Pattern B for dynamic features
<YourEntitySelect
  value={selectedNames}           // Name-based value
  filter={externalFilter}         // 🔑 Dynamic filter
  pageSize={20}                   // 🔑 Dynamic limit
  sortBy="name"                   // 🔑 Dynamic order
  ref={selectRef}                 // 🔑 Refetch capability
/>

Best Practices

Performance

1. Use 'use memo' directive (Pattern B)

   const YourSelect: React.FC<Props> = (props) => {
     'use memo';
     // Component logic
   };
   

2. Defer values to prevent Suspense flicker

   const deferredOpen = useDeferredValue(open);
   const deferredValue = useDeferredValue(value);
   const deferredFetchKey = useDeferredValue(fetchKey);
   

   Search optimization with useDebouncedDeferredValue (Recommended):

   import useDebouncedDeferredValue from '../../helper/useDebouncedDeferredValue';
   
   const [searchStr, setSearchStr] = useState<string>();
   const debouncedDeferredValue = useDebouncedDeferredValue(searchStr, {
     wait: 200, // default
   });
   const [optimisticSearchStr, setOptimisticSearchStr] =
     useOptimistic(searchStr);
   

   Why useDebouncedDeferredValue?

   • ✅ Combines useDebounce + useDeferredValue for optimal search performance
   • ✅ Debounces user input to reduce query frequency (default 200ms)
   • ✅ Defers query execution to prevent UI blocking
   • ✅ Use optimisticSearchStr for immediate input feedback
   • ✅ Use debouncedDeferredValue in query filters
   • ✅ Better performance than debounce or defer alone
   • ✅ Prevents excessive GraphQL queries during fast typing

   Pattern comparison:

   // ❌ Old: Only useDeferredValue (too many queries)
   const deferredSearchStr = useDeferredValue(searchStr);
   
   // ❌ Old: Only useDebounce (can still block UI)
   const debouncedSearchStr = useDebounce(searchStr);
   
   // ✅ New: Combined approach (optimal)
   const debouncedDeferredValue = useDebouncedDeferredValue(searchStr);
   

3. Optimize fetchPolicy

   // Selected values
   fetchPolicy: !_.isEmpty(value) ? 'store-or-network' : 'store-only'
   
   // Paginated options
   fetchPolicy: deferredOpen ? 'network-only' : 'store-only'
   

4. Skip unnecessary queries

   @skip(if: $skipSelected)
   

UX

1. Always scroll to top on search

   selectRef.current?.scrollTo(0);
   

2. Maintain selection order

   _.castArray(deferredValue)
     .map((v) => findEdge(v))
     .filter(Boolean);
   

3. Handle React element labels

   const label = _.isString(v.label)
     ? v.label
     : (options.find((opt) => opt.value === v.value)?.label ?? v.value);
   

4. Custom label rendering for IDs

   import { toLocalId } from '../../helper';
   import BAIText from '../BAIText';
   
   labelRender={({ label }) => {
     return valuePropName === 'id' && _.isString(label) ? (
       <BAIText monospace>{toLocalId(label)}</BAIText>
     ) : (
       label
     );
   }}
   optionRender={({ label }) => {
     return valuePropName === 'id' && _.isString(label) ? (
       <BAIText monospace>{toLocalId(label)}</BAIText>
     ) : (
       label
     );
   }}
   

   Benefits:

   • Convert Global IDs to local IDs for better readability
   • Consistent monospace rendering for ID values
   • Conditional rendering based on valuePropName

5. Loading state priorities

   loading={
     loading ||
     controllableValue !== deferredControllableValue ||
     searchStr !== debouncedDeferredValue ||  // Show loading during debounce + defer
     isPendingRefetch
   }
   // Note: searchStr comparison is needed to show loading during debounce + defer period
   // useOptimistic handles immediate input feedback
   

Common Pitfalls & Solutions

Pitfall	Impact	Solution
Missing first parameter	Incomplete selected values	REQUIRED in Pattern B: Add $first: Int! parameter
Hardcoded first: 10	Missing data for >10 selections	Pattern B always uses: _.castArray(value).length
Not checking _.isEmpty() before _.castArray()	Potential issues with empty values	Use _.isEmpty(value) ? [] : _.castArray(value)
Missing _.castArray	Single mode breaks	Always normalize values
Not using deferredValue	Suspense flicker	Defer controllable values (value, open, fetchKey)
Not using useOptimistic for search	Poor search UX	Use useOptimistic for immediate feedback
Not using useDebouncedDeferredValue	Too many queries	Use useDebouncedDeferredValue for search
Missing loading condition	No loading feedback	Add searchStr !== debouncedDeferredValue
Missing @skip directive	Unnecessary queries	Add skip when empty
Not preserving labels	Lost labels on tag removal	Check if label is string or element
Hardcoded valuePropName	Inflexible component	Use prop: 'id' | 'row_id'
Direct option mutation	Stale data	Rebuild from query results
No scroll on search	Poor UX	Call selectRef.current?.scrollTo(0)
Wrong fetchPolicy	Performance issues	Use appropriate policy per query
Hardcoded showSearch object	Can't disable search	Use conditional pattern with showSearch === false check
Not using optimisticSearchStr	Delayed search feedback	Use useOptimistic for searchValue
Not merging user showSearch	Inflexible configuration	Merge with _.omit(selectProps.showSearch, ['searchValue'])

TypeScript Patterns

Props Interface

export interface YourComponentSelectProps
  extends Omit<BAISelectProps, 'options' | 'labelInValue'> {
  // Pattern A
  queryRef?: YourFragment$key;

  // Pattern B
  valuePropName?: 'id' | 'row_id';
  filter?: string;
  ref?: React.Ref<YourComponentRef>;
}

Ref Interface (Pattern B)

export interface YourComponentRef {
  refetch: () => void;
}

Type Extraction (Pattern B)

export type YourEntityNode = NonNullable<
  NonNullable<
    YourPaginatedQuery['response']['yourEntities']
  >['edges'][number]
>['node'];

Real-World Examples

Example 1: Simple Entity Selection (Pattern A)

// Scenario: Select resource group by name
<BAIAdminResourceGroupSelect
  queryRef={queryRef}
  placeholder="Select resource group"
  onChange={(name) => setSelectedGroup(name)}
/>

Example 2: Multiple Selection with ID (Pattern B)

const vfolderSelectRef = useRef<BAIVFolderSelectRef>(null);

<BAIVFolderSelect
  ref={vfolderSelectRef}
  valuePropName="id"
  mode="multiple"
  value={selectedFolderIds}
  onChange={setSelectedFolderIds}
  onClickVFolder={(id) => navigate(\`/folders/\${id}\`)}
/>

<Button onClick={() => vfolderSelectRef.current?.refetch()}>
  Refresh
</Button>

Example 3: With External Filters (Pattern B)

<BAIVFolderSelect
  filter={mergeFilterValues([
    'status != "DELETE_COMPLETE"',
    ownershipFilter ? \`ownership_type == "\${ownershipFilter}"\` : null,
  ])}
  excludeDeleted
  onChange={(ids) => handleSelection(ids)}
/>

Quick Reference

When to Use Which Pattern

Pattern A (Simple) when:

• ✅ Simple, static requirements
• ✅ Single selection sufficient
• ✅ No need for dynamic query parameters
• ✅ Minimal code preferred
• ✅ No external refetch needed

Pattern B (Dynamic) when:

• ✅ Need dynamic query parameters (filter, first, limit, order, etc.)
• ✅ Multiple selection required
• ✅ Need external refetch capability via ref
• ✅ Need to control fetchPolicy dynamically
• ✅ Optimistic UI updates important
• ✅ Complex filter combinations needed
• ✅ Value different from display name (or needs special handling)
• ✅ Even name-based values if dynamic control needed

Key insight: Pattern B is not about the value type (email vs ID vs name), but about dynamic control over query parameters and component behavior.

Reference Files

• Pattern A (Simple): references/patterns/BAIAdminResourceGroupSelect.md
• Pattern B (Dynamic):
  • Email-based with Dynamic First: references/patterns/BAIUserSelect.md
  • ID-based with Dynamic First & Global ID Conversion: references/patterns/BAIVFolderSelect.md
• Base Component: references/base/BAISelect.md
• Hooks: references/hooks/ (useFetchKey, useLazyPaginatedQuery, useDebouncedDeferredValue, useEventNotStable)
• Helpers: references/helpers/ (relay-helpers, mergeFilterValues)

File Structure

YourEntitySelect.tsx
├── Imports (React, Relay, hooks, helpers)
├── Type definitions (Props, Ref, Node extraction)
├── Component with 'use memo'
│   ├── State management
│   ├── GraphQL queries
│   ├── Value-to-label mapping (Pattern B)
│   ├── useImperativeHandle (Pattern B)
│   ├── Options building
│   └── BAISelect integration
└── Export

Internationalization

Use comp: prefix for component translations:

t('comp:YourComponentSelect.PlaceHolder')
t('comp:YourComponentSelect.SelectEntity')
t('comp:YourComponentSelect.NoEntityFound')

Additional Resources

For comprehensive examples and detailed implementation, refer to:

• references/README.md - File overview and usage notes
• Full pattern implementations in references/patterns/
• Base component API in references/base/
• Hook documentation in references/hooks/
• Helper utilities in references/helpers/