Fix: BTable row-details get hidden on "Load more"

Fixes row-details being hidden when items array is updated with new object references.

Problem

When using BTable/BTableLite with row-details, if the items array is replaced with new objects (even with the same data), the row-details would be hidden. This commonly happens in "Load more" scenarios where the entire items array is recreated.

Root Cause: The detailsMap used a WeakMap with object references as keys. When items were replaced with new objects, the map lost track of which rows had details open.

Solution

Updated BTableLite to dynamically use the appropriate map type and track by primary key when available:

• Use WeakMap when no primaryKey - for memory efficiency (garbage collection of unused items)
• Use Map when primaryKey is defined - to support string keys for primary key tracking
• Watch for primaryKey changes - recreate the map when the primaryKey prop changes
• Modified generateDetailsItem to return the primary key string when primaryKey prop is provided and the item contains that key
• Added helper functions for type-safe map operations that handle the union type correctly
• Updated watcher logic to preserve existing details state when items are replaced with the same primary key value
• Falls back to object reference tracking when no primaryKey is provided (maintains full backward compatibility)
• Added concise documentation about primary key behavior in row details section

Usage

To enable row-details persistence across item updates, provide a primary-key prop:

<BTable :items="items" :fields="fields" primary-key="id">
  <template #cell(actions)="row">
    <BButton @click="row.toggleDetails">
      {{ row.detailsShowing ? 'Hide' : 'Show' }} Details
    </BButton>
  </template>
  <template #row-details="row">
    <BCard>Details for {{ row.item.name }}</BCard>
  </template>
</BTable>

When items are updated (e.g., in a "Load more" scenario):

// Items are replaced with new object references but same IDs
items.value = [
  { id: 1, name: 'Alice', age: 30 },  // New object but id: 1 remains
  { id: 2, name: 'Bob', age: 25 },    // New object but id: 2 remains
  { id: 3, name: 'Charlie', age: 35 } // New item added
]
// Row-details for items with id 1 and 2 will persist if they were open

Demo

The fix is demonstrated with two tables - one with primary-key and one without:

• Top table (with primary-key): Alice's details remain open after clicking "Load More" ✅
• Bottom table (without primary-key): Alice's details are closed after clicking "Load More" (expected behavior for backward compatibility)

Changes

Core Implementation (BTableLite.vue):

• detailsMap: Dynamically initialized as WeakMap (no primaryKey) or Map (with primaryKey)
• Added watcher for primaryKey prop changes - clears and recreates map with appropriate type
• generateDetailsItem: Returns primary key string when primaryKey prop is provided
• Added helper functions:
  • hasDetailsValue: Type-safe .has() check
  • setDetailsValueByKey: Type-safe .set() operation
  • getDetailsMapKey: Consistent key generation
  • getDetailsValue: Type-safe .get() for items
  • setDetailsValue: Type-safe .set() for items
• Updated all map operations to use helper functions

Documentation (table.md):

• Added concise note in Row details support section explaining primary key behavior
• Mentions persistence with primary key, WeakMap usage without primary key, and garbage collection behavior

Tests (table-lite.spec.ts):

• Added test: "persists details when items are replaced with new object references but same primary key"
• Added test: "falls back to object reference when primaryKey is not provided"
• Added test: "clears details when primaryKey prop changes"
• Added test: "clears details when primaryKey is removed"
• Added test: "clears details when primaryKey is changed and then changed back"
• All existing tests continue to pass (1635 tests total)

Behavior

Memory Efficiency

Using WeakMap when no primaryKey is provided ensures:

• Items that are no longer referenced can be garbage collected
• No memory leaks from holding references to old item objects
• Automatic cleanup when items are removed from the table

Backward Compatibility

✅ Fully backward compatible - when no primaryKey is provided, uses WeakMap (memory efficient, original behavior). When primaryKey is provided, uses Map (supports primary key tracking). This is a progressive enhancement that only activates when the primary-key prop is used.

Testing

• ✅ All unit tests pass (1635 tests)
• ✅ Linting passes
• ✅ Build succeeds
• ✅ Manual testing confirms fix works as expected
• ✅ Documentation added and verified

Fixes #2870

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.