feat: allow one file column to be mapped to multiple Salesforce fields

[paustint]

allow one file column to be mapped to multiple Salesforce fields

Loading the same column into two Salesforce fields, or using
it both as a value and as a lookup reference, previously required
duplicating the column in the source file.

Closes #646

[Copilot]

Pull request overview

This PR enhances the Load Records field-mapping UX to allow mapping a single input-file column into multiple Salesforce fields (including mixing direct field mapping and lookup/reference mapping), eliminating the need to duplicate columns in the source file.

Changes:

• Introduces “additional mapping” rows keyed by synthetic mapping keys while still reading values from the original csvField.
• Updates saved-mapping persistence/restoration to support synthetic keys safely (re-keying on load to avoid collisions).
• Adds UI controls (+ / remove) and documentation to support and explain multi-mapping behavior.

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
libs/shared/ui-core/src/load/load-records-utils.tsx	Adds additional-mapping/static-row helpers and updates saved-mapping hydration + transform behavior to read from csvField.
libs/shared/ui-core/src/load/tests/load-records-utils.spec.ts	Adds coverage for additional mappings, hydration rules, and transform behavior.
libs/shared/constants/src/lib/shared-constants.ts	Adds an analytics key for “additional mapping added” tracking.
libs/features/load-records/src/steps/FieldMapping.tsx	Derives additional/static rows from mapping object and adds UI actions to create/remove additional mappings.
libs/features/load-records/src/LoadRecords.tsx	Updates “fields mapped” summary to count distinct file columns mapped (not mapping rows).
libs/features/load-records/src/components/LoadRecordsFieldMappingRowLookupOption.tsx	Switches callback identity from csvField to mappingKey for synthetic-key rows.
libs/features/load-records/src/components/LoadRecordsFieldMappingRow.tsx	Adds UI for additional mappings (+ and remove) and passes mappingKey through selection changes.
libs/features/load-records/src/components/LoadRecordsFieldMappingRelatedObject.tsx	Propagates mappingKey through related-object/lookup option editing.
libs/features/load-records/src/components/load-mapping-storage/SaveMappingPopover.tsx	Saves csvFields using field.csvField so additional mappings record the real column.
libs/features/load-records/src/components/load-mapping-storage/SaveMappingItem.tsx	Updates tooltip list keying to support multiple rows with the same csvField.
libs/features/load-records/src/components/load-mapping-storage/LoadMappingPopover.tsx	Updates saved-mapping availability checks to ignore static placeholders via helper.
apps/docs/docs/load/load.mdx	Documents mapping one column to multiple fields via the new “+” control.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[paustint]

Code review summary

Automated review (Claude Code). Fixes below are pushed as an amend to the PR head.

Verdict: careful, well-tested data-shape change — the FieldMapping key/csvField split is honored at every consumer traced. No outstanding decisions.

Verified clean: transformData csvField read, duplicate-field validation, all DOM id / React key / radio-name collisions (correctly moved to mappingKey), saved-mapping backward compatibility including the uniqueId re-key fix, and autoMap/clear/reset.

Fixed and pushed

• load-records-utils.tsx — saved mappings resurrected stale errors. fieldErrorMsg and isDuplicateMappedField were persisted to storage and restored verbatim, so a mapping saved while in an error state came back permanently broken and blocked the next step with no way to clear it. hydrateSavedMappingItem now clears both so validation recomputes against the current file and object. Because this happens on restore rather than save, it also heals records already in storage.
• SaveMappingItem.tsx — raw placeholder shown to users. The tooltip rendered the internal ~STATIC~MAPPING~N placeholder as the source column name. Now renders "Manual value" via the existing isStaticValuePlaceholder helper.
• Added a regression test for the cleared validation state. Verified by negative control: with the fix reverted the new test fails on the resurrected fieldErrorMsg, so it genuinely guards the behavior.

(ui-core 185 tests, features-load-records 71 tests, typecheck all pass.)

Note

No Playwright coverage for the mapping UI — a pre-existing gap, not introduced here.