feat(workbench): various UX improvements

[grantfitzsimmons]

Fixes #8153
Fixes #8155
Fixes #8014
Fixes #4484

This PR introduces a number of different UI improvements, localization updates, and bug fixes centered around the WorkBench data mapping and upload workflows:

1. Terminology Updates ("Upload Plan" ➔ "Mapping"):

   • Renamed user-facing copy and localized strings from "Upload Plan" to "Mapping" / "Mapping Plan" (e.g. chooseExistingPlan becomes "Choose Existing Mapping", uploadPlan is now "Import/Export Mapping").

2. Record Counts & Live Validation:

   • Validation and upload results dialogs now dynamically show a breakdown of record counts per type (e.g., Created, Updated, Deleted, Matched/Changed) using the TableRecordCounts component.
   • Enabled Live Validation (dataCheck) by default (defaultValue: true in user preferences).
   • Dialog icons now accurately reflect the validation and upload status (success, error, warning).
     
     
     
     

3. Import/Export Mapping Enhancements:

   • Added the ability to import a mapping configuration from a .json file in addition to exporting.
   • Includes validation to show an error dialog if the uploaded file is not valid JSON.
     
     

4. Data Mapping Dialog & Usability Improvements:

   • Added a "Choose Existing Mapping" option directly in the "no mapping" dialog.
     
   • Added a confirmation step before clearing all mappings to prevent accidental loss of progress.
     
   • Added descriptive helper texts in the Base Table Selection dialogs explaining what a base table is, and adjusted the dialog container layout to a more standard sizing constraint.
     WorkBench
     
     WorkBench Attachments
     
   • Added documentation link to the workbench mapper control panel.
     

5. UI Fixes:

   • Firefox SvgIcon Rendering (Fixes WorkBench table icons appear incorrectly in Firefox #8155): Switched the text centering alignment properties to dy=".35em" on <text> elements in SvgIcon.tsx to fix icon rendering bugs in Firefox.
   • Express Search Config Dialog (Fixes Dialog width for express search config shifts depending on selection #8014): Switched dialog layout to dialogClassNames.extraWideContainer to prevent container shifting and clipping.
     

Checklist

• Self-review the PR after opening it to make sure the changes look good and
  self-explanatory (or properly documented)
• Add relevant issue to release milestone
• Add pr to documentation list
• Add automated tests
• Add a reverse migration if a migration is present in the PR
• Add migration function to

  specify7/specifyweb/specify/management/commands/run_key_migration_functions.py

  Line 50 in ea04665

  def fix_schema_config(stdout: WriteToStdOut | None = None):

---

Testing instructions

1. Live Validation & Upload Record Counts (Fixes #8153)

• Open any dataset in the WorkBench.
• Verify that "Live Validation" is enabled by default.
• Map your columns and trigger validation/upload.
• Verify that the validation and upload confirmation/results dialogs show a table outlining the records created, updated, deleted, or matched/changed, depending on your dataset operations.

2. Mapping Import/Export & Clear Confirmation

• While mapping columns, click Import/Export Mapping (previously "Upload Plan").
• Verify that you can Export the current plan as a .json file.
• Test the Import feature by selecting a .json file from your local machine. Verify that uploading a corrupt or invalid JSON file presents an invalid JSON error dialog.
• Click Clear Mappings and ensure a confirmation dialog appears asking to verify erasing the mappings before proceeding.
• Switch datasets to one without a mapping. Verify that the dialog now includes a button to Choose Existing Mapping.

3. Base Table Selection Dialog

• Open the Base Table Selection dialog (e.g. by changing base tables or starting a new mapping).
• Verify the dialog width/height scales properly and that it displays descriptions clarifying what a "base table" is.

4. SvgIcon Alignment in Firefox (Fixes #8155)

• Open the WorkBench using Firefox.
• Verify that column/table status icons align correctly and do not shift out of place.

5. Express Search Dialog Shifting (Fixes #8014)

• Open the Express Search Configuration dialog.
• Verify the dialog does not shift layout when opened/closed.

Summary by CodeRabbit

Summary

• New Features

  • Added “choose existing plan” when no upload plan is available
  • Added JSON import/export support for raw mapping plans (with validation) and a richer upload-start dialog with record-count breakdowns
  • Added “clear mappings” confirmation and a new mapping documentation link

• Improvements

  • Updated dialog/icon behavior (including question prompts) and improved dialog sizing and UI text across the WorkBench
  • Enhanced results panel behavior using cell counts; refined live validation visibility

• Bug Fixes

  • Improved warning/question/failure icon styling and clarified relationship-mapping failure messaging

[grantfitzsimmons]

@CarolineDenis:

I don't think live validation is enabled by default.

I suppose I mean that the live validation button is visible by default rather than on automatically. Do you think it would be intrusive if it started as soon as data was being entered?

[CarolineDenis]

@grantfitzsimmons ok then it works as expected!
I think the current behavior is best.

[emenslin]

1. Live Validation & Upload Record Counts (Fixes #8153)

• Verify that "Live Validation" is enabled by default.
• Verify that the validation and upload confirmation/results dialogs show a table outlining the records created, updated, deleted, or matched/changed, depending on your dataset operations.

2. Mapping Import/Export & Clear Confirmation

• Verify that you can Export the current plan as a .json file.
• Test the Import feature by selecting a .json file from your local machine. Verify that uploading a corrupt or invalid JSON file presents an invalid JSON error dialog.
• Click Clear Mappings and ensure a confirmation dialog appears asking to verify erasing the mappings before proceeding.
• Switch datasets to one without a mapping. Verify that the dialog now includes a button to Choose Existing Mapping.

3. Base Table Selection Dialog

• Verify the dialog width/height scales properly and that it displays descriptions clarifying what a "base table" is.

4. SvgIcon Alignment in Firefox (Fixes #8155)

• Verify that column/table status icons align correctly and do not shift out of place.

5. Express Search Dialog Shifting (Fixes #8014)

• Verify the dialog does not shift layout when opened/closed.

---

Overall it looks really good! I didn't run into any major issues but I have a few questions.

• When first looking at results after live validation it shows completely incorrect results and you have to close the dialog and open it again for the results to show correctly. Regular validation does appear correctly first time around so I am not too worried about it since a regular validation is recommended before uploading anyway; however, I figured it was still worth mentioning

06-08_12.47.mp4

• If you import an invalid JSON file or edit the existing file to be invalid, there is no error, instead it just doesn't let you save when you press save.

06-08_12.01.mp4

• Live validation says a row needs to be disambiguated but doesn't let you disambiguate

06-08_10.53.mp4

• Live validation count disappears after it's been run once

• Results and the new records in upload dialog are in opposite orders, this doesn't necessarily matter, but it could be worth considering what way is the best way to display the new records.

• Should the import mapping dialog match other import dialogs? i.e. have the box where you can choose a file or drag it

  • Example when importing a WB data set
  

• Lastly, when you import a mapping the columns are sometimes in the incorrect order from the file. I'm getting similar behavior in main so it isn't specific to this issue but I figured it was worth mentioning.

06-08_13.02.mp4

[grantfitzsimmons]

More notes: It seems 'Live Validation' believes it is validating a WorkBench data set even in Batch Edit. For example, I was batch editing Collection Object records and used live validation, but it complained about duplicate catalog numbers. I suggest we disable it for Batch Edit in this PR.

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

specifyweb/frontend/js_src/lib/components/WbActions/useResults.ts (1)

40-77: 🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

Re-show previously filtered rows/columns before applying the new result set.

This effect now reruns on cellCounts changes, but it only hides. If a later validation/update makes a row or column contain results, it stays hidden from the earlier run until the panel is closed, so the open results view can only shrink.

Possible fix

   React.useEffect(() => {
     if (hot === undefined || !showResults) return;
+    const hiddenRows = getHotPlugin(hot, 'hiddenRows');
+    const hiddenColumns = getHotPlugin(hot, 'hiddenColumns');

     const rowsToInclude = new Set<number>();
     const colsToInclude = new Set<number>();
     Object.entries(workbench.cells.cellMeta).forEach(([physicalRow, rowMeta]) =>
       rowMeta.forEach((metaArray, physicalCol) => {
@@
     hot.batch(() => {
       identifyDefaultValues(hot, workbench.mappings);
-      getHotPlugin(hot, 'hiddenRows').hideRows(rowsToHide);
-      getHotPlugin(hot, 'hiddenColumns').hideColumns(colsToHide);
+      hiddenRows.showRows(
+        hiddenRows
+          .getHiddenRows()
+          .filter((row) => !initialHiddenRows.includes(row))
+      );
+      hiddenColumns.showColumns(
+        hiddenColumns
+          .getHiddenColumns()
+          .filter((column) => !initialHiddenCols.includes(column))
+      );
+      hiddenRows.hideRows(rowsToHide);
+      hiddenColumns.hideColumns(colsToHide);
       workbench.utils.toggleCellTypes('newCells', 'remove');
     });
   }, [showResults, cellCounts]);

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@specifyweb/frontend/js_src/lib/components/WbActions/useResults.ts` around
lines 40 - 77, The `useResults` effect only hides rows/columns and never
restores ones that were hidden by a previous run, so the results view can only
shrink as `cellCounts` changes. Update the `React.useEffect` in `useResults` to
re-show the previously hidden rows/columns before computing and applying the new
hidden sets, using the existing `hiddenRows` and `hiddenColumns` plugins around
the `identifyDefaultValues`, `hideRows`, and `hideColumns` calls. Keep the
existing `showResults`, `cellCounts`, `hot`, `initialHiddenRows`, and
`initialHiddenCols` logic intact while ensuring newly result-containing
rows/columns become visible again.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Outside diff comments:
In `@specifyweb/frontend/js_src/lib/components/WbActions/useResults.ts`:
- Around line 40-77: The `useResults` effect only hides rows/columns and never
restores ones that were hidden by a previous run, so the results view can only
shrink as `cellCounts` changes. Update the `React.useEffect` in `useResults` to
re-show the previously hidden rows/columns before computing and applying the new
hidden sets, using the existing `hiddenRows` and `hiddenColumns` plugins around
the `identifyDefaultValues`, `hideRows`, and `hideColumns` calls. Keep the
existing `showResults`, `cellCounts`, `hot`, `initialHiddenRows`, and
`initialHiddenCols` logic intact while ensuring newly result-containing
rows/columns become visible again.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 338596a0-264d-4203-936f-6597d3bdc594

📥 Commits

Reviewing files that changed from the base of the PR and between 912cb6a and e3fb771.

📒 Files selected for processing (10)

• specifyweb/frontend/js_src/lib/components/Header/ExpressSearchTask.tsx
• specifyweb/frontend/js_src/lib/components/WbActions/WbNoUploadPlan.tsx
• specifyweb/frontend/js_src/lib/components/WbActions/WbValidate.tsx
• specifyweb/frontend/js_src/lib/components/WbActions/useResults.ts
• specifyweb/frontend/js_src/lib/components/WbPlanView/Mapper.tsx
• specifyweb/frontend/js_src/lib/components/WbToolkit/DevShowPlan.tsx
• specifyweb/frontend/js_src/lib/components/WorkBench/WbView.tsx
• specifyweb/frontend/js_src/lib/localization/batchEdit.ts
• specifyweb/frontend/js_src/lib/localization/wbPlan.ts
• specifyweb/frontend/js_src/lib/localization/workbench.ts

✅ Files skipped from review due to trivial changes (2)

• specifyweb/frontend/js_src/lib/localization/batchEdit.ts
• specifyweb/frontend/js_src/lib/localization/workbench.ts

🚧 Files skipped from review as they are similar to previous changes (4)

• specifyweb/frontend/js_src/lib/components/WbPlanView/Mapper.tsx
• specifyweb/frontend/js_src/lib/components/WbActions/WbNoUploadPlan.tsx
• specifyweb/frontend/js_src/lib/localization/wbPlan.ts
• specifyweb/frontend/js_src/lib/components/WbToolkit/DevShowPlan.tsx

[grantfitzsimmons]

Re: @emenslin

• When first looking at results after live validation it shows completely incorrect results and you have to close the dialog and open it again for the results to show correctly. Regular validation does appear correctly first time around so I am not too worried about it since a regular validation is recommended before uploading anyway; however, I figured it was still worth mentioning

This should be fixed.

• If you import an invalid JSON file or edit the existing file to be invalid, there is no error, instead it just doesn't let you save when you press save.

This was fixed by using CodeMirror as we do in App Resources here.

• Live validation says a row needs to be disambiguated but doesn't let you disambiguate

I can't recreate this, but it still falls outside the scope of this PR (ostensibly, at least). Can you open a bug if you can recreate this consistently? I think it has to do with that specific agent being created in the same data set in two different roles (e.g. determiner, collector) twice.

• Live validation count disappears after it's been run once

This is intentional, as far as I can tell. That number represented the number of rows still to validate.

• Results and the new records in upload dialog are in opposite orders, this doesn't necessarily matter, but it could be worth considering what way is the best way to display the new records.

Good idea, implemented:

• Should the import mapping dialog match other import dialogs? i.e. have the box where you can choose a file or drag it

No, I'd like to keep it distinct. It's not a bad suggestion, but this is an intentional design decision. If you clear the value from the editor, you can actually drag a file into it:

Screen.Recording.2026-06-29.at.7.47.23.PM.mov

• Lastly, when you import a mapping the columns are sometimes in the incorrect order from the file. I'm getting similar behavior in main so it isn't specific to this issue but I figured it was worth mentioning.

Can you open a new issue for this? This is an existing bug.