@xeplr/ui-utils 1.0.11 → 1.0.12

package/README.md

@@ -74,7 +74,7 @@ export default function SelectCompany() {
    }
    ```
 
-3. **Model only.** The model files import neither React nor the DOM: `dateRange.js`, `rangeField.js`, `textField.js`, `numberField.js`, `dateField.js`, `dropdown.js`, `gridDisplayer.js`, `dataImport.js`, `droppedRows.js`, and `theme/index.js`. They are exported from the root (for a bundler). In plain Node, import the file directly, because the root index pulls in JSX, CSS and JSON. The tests do this:
+3. **Model only.** The model files import neither React nor the DOM: `dateRange.js`, `rangeField.js`, `textField.js`, `numberField.js`, `dateField.js`, `dropdown.js`, `gridDisplayer.js`, `dataImport.js` (with `IMPORT_MODES`, `DEFAULT_MODE`, `targetProblems`, `blocksImport`, `canRollback`, `modeLabel`), `droppedRows.js`, `imports/importsApi.js` (fetch only), and `theme/index.js`. They are exported from the root (for a bundler). In plain Node, import the file directly, because the root index pulls in JSX, CSS and JSON. The tests do this:
 
    ```js
    import { resolveDateValue } from '@xeplr/ui-utils/src/dateRange/dateRange.js'
@@ -97,6 +97,7 @@ export default function SelectCompany() {
 | `NumberFieldPage` | [see below](#numberfieldpage) | Float, currency or units input with an affix picker |
 | `TextFieldPage` | [see below](#textfieldpage) | Text, multiline or search input, themed by `--xeplr-input-text-*` |
 | `FileUploadPage` | [see below](#fileuploadpage) | Drag-and-drop upload with type and size checks and a progress bar |
+| `ImportsPage` | [see below](#importspage) | The whole import screen against `@xeplr/imports`: database picker, import, progress, history |
 | `DataImportPage` | [see below](#dataimportpage) | Upload a file, map its parts to targets, commit |
 | `ImportHistoryPage` | [see below](#importhistorypage) | Past imports in a `XeplrTable`, with Rollback and Delete |
 | `DroppedRowsPage` | [see below](#dropped-rows) | The rows an import's database refused, in a dialog: row, reason, Copy, Download. Built into the two pages above |
@@ -106,7 +107,7 @@ export default function SelectCompany() {
 | `SettingsTreePage` | [see below](#panel-panelsection-panelfield-expanderspage) | Nested groups of settings: cards, branches on a rail, one open per level |
 | `PanelSection`, `PanelField` | [see below](#panel-panelsection-panelfield-expanderspage) | A section card with an icon; a row with the label left and help under the control |
 | `ProgressNotifier` | [see below](#progressnotifier) | Indeterminate bar and a line of text for one event key |
-| `FileUploadSample`, `DataImportSample`, `ImportHistorySample`, `DroppedRowsSample`, `NumberFieldSample`, `DateFieldSample`, `DateRangeSample`, `RangeFieldSample`, `DropdownSample`, `GridDisplayerSample`, `TextFieldSample`, `ColorPickerSample`, `ExpandersSample`, `SettingsTreeSample` | the matching controller's return value | The default designs, usable on their own |
+| `FileUploadSample`, `ImportsSample`, `DataImportSample`, `ImportHistorySample`, `DroppedRowsSample`, `NumberFieldSample`, `DateFieldSample`, `DateRangeSample`, `RangeFieldSample`, `DropdownSample`, `GridDisplayerSample`, `TextFieldSample`, `ColorPickerSample`, `ExpandersSample`, `SettingsTreeSample` | the matching controller's return value | The default designs, usable on their own |
 
 ### Controllers (hooks)
 
@@ -119,7 +120,8 @@ export default function SelectCompany() {
 | `useNumberFieldController(props)` | NumberFieldPage props | `type, raw, numeric, error, placeholder, disabled, decimals, formatDisplay, affix {list, selected, position, labelKey, valueKey} \| null, handleNumberChange, handleAffixChange, handleBlur` |
 | `useTextFieldController(props)` | TextFieldPage props | `type, raw, error, remaining, placeholder, disabled, required, maxLength, rows, label, help, handleChange, handleBlur, handleKeyDown, handleClear` |
 | `useFileUploadController(options)` | FileUploadPage props | `files, uploading, progress, error, result, dragOver, inputRef, handleChange, handleDragOver, handleDragLeave, handleDrop, handleUpload, openFilePicker, removeFile(i), clear, allowedTypes, maxSize, maxFiles` |
-| `useDataImportController(options)` | DataImportPage props | `file, inspecting, inspected, mappings, committing, results, error, handleFileChange, updateMapping(i, patch), setFix(i, key, on), checksOf(part), handleCommit, reset, accept, targetLabel` |
+| `useImportsController(props)` | ImportsPage props | `targets, targetsError, connectionId, dbInfoId, databases, chooseConnection, chooseDatabase, importing, progressText, stop, historyVersion, importProps, historyProps` |
+| `useDataImportController(options)` | DataImportPage props | `file, inspecting, uploadPercent, inspected, mappings, committing, results, error, handleFileChange, updateMapping(i, patch), setFix(i, key, on), checksOf(part), modes, setMode(i, mode), problems (per mapping), checking, blocked, handleCommit, reset, accept, targetLabel` |
 | `useImportHistoryController(options)` | ImportHistoryPage props | `jobs, loading, error, rollingBackId, deletingId, reload, handleRollback(job), handleDelete(job)` |
 | `useDroppedRowsController(options)` | `onLoadDropped`, `onDownloadDropped` | `job, data, table {columns, rows}, summary {heading, note}, loading, error, copied, downloading, canCopy, canDownload, canView(job), open(job), close, copy, download` |
 | `useGridDisplayerController(props)` | GridDisplayerPage props | `query, setQuery, sortFields, sortValue, setSortValue, displayRows, tileFormatComponent, onSelect, onAddNew` |
@@ -167,7 +169,7 @@ export default function SelectCompany() {
 | `deepMerge` | `(base, override)` | Immutable merge. Arrays are replaced, and `undefined` never overwrites a value. |
 | `COUNTRIES` | `[{ code, name }]` | 196 countries |
 | `STATES`, `STATES_IN` | `{ IN: [{ code, name }] }`, `[{ code, name }]` | 36 Indian states and union territories |
-| `FILE_UPLOAD_RULES`, `DATA_IMPORT_RULES`, `IMPORT_HISTORY_RULES`, `DROPPED_ROWS_RULES`, `NUMBER_FIELD_RULES`, `DATE_FIELD_RULES`, `DATE_RANGE_RULES`, `RANGE_FIELD_RULES`, `DROPDOWN_RULES`, `GRID_DISPLAYER_RULES`, `TEXT_FIELD_RULES`, `COLOR_PICKER_RULES`, `EXPANDERS_RULES`, `SETTINGS_TREE_RULES` | rule arrays | What each page requires of a design |
+| `FILE_UPLOAD_RULES`, `IMPORTS_RULES`, `DATA_IMPORT_RULES`, `IMPORT_HISTORY_RULES`, `DROPPED_ROWS_RULES`, `NUMBER_FIELD_RULES`, `DATE_FIELD_RULES`, `DATE_RANGE_RULES`, `RANGE_FIELD_RULES`, `DROPDOWN_RULES`, `GRID_DISPLAYER_RULES`, `TEXT_FIELD_RULES`, `COLOR_PICKER_RULES`, `EXPANDERS_RULES`, `SETTINGS_TREE_RULES` | rule arrays | What each page requires of a design |
 
 ## DropdownPage
 
@@ -292,20 +294,63 @@ configureUpload({ url: '/uploads', getHeaders: () => ({ Authorization: 'Bearer '
 
 `uploadFile` POSTs `multipart/form-data` with `XMLHttpRequest`, so it can report upload progress. The default URL is `/internal/upload`. `getHeaders()`, if set, is called on **every** upload, so headers such as an auth token are always current. Otherwise the static `headers` are used. The response must be JSON. A non-2xx response rejects with the response's `error` or "Upload failed". If any picked file breaks a rule, the whole selection is rejected with a message naming that file.
 
+## ImportsPage
+
+The whole import feature, against [`@xeplr/imports`](https://www.npmjs.com/package/@xeplr/imports)' routes. An app that mounts that router adds one route here and nothing else:
+
+```jsx
+configureUpload({ url: API_BASE + '/imports/files', getHeaders })   // once, at startup — the headers every call carries
+<Route path="/upload" element={<ImportsPage basePath={API_BASE + '/imports'} />} />
+```
+
+| prop | type | meaning |
+|---|---|---|
+| `basePath` | `string` | Where the app mounted the router, as the browser sees it (default `'/imports'`) |
+| `pollMs` | `number` | How often a running import is asked how far it has got (default 1000) |
+
+It shows three things:
+
+1. **The database picker**, filled from `GET /targets`.
+2. **The import itself.** This is `DataImportPage`: its checks, the New table / Append / Replace modes with the file checked against the typed table, the upload percentage, and the dropped rows. While an import runs, its progress shows with its running time and ✕.
+3. **The history.** This is `ImportHistoryPage`, with dropped rows, rollback (none for a Replace) and delete.
+
+Requests carry the headers `configureUpload` was given (`uploadHeaders()`), so sign-in and tenancy need no second setup. The model is `importsApi.js`:
+
+- `createImportsApi(basePath)` makes every route call.
+- Pure helpers: `importProgressText`, `runResults`, `historyJob`, `databasesOf`, `fileNameOf`.
+
+A custom design receives the controller's values plus `importSection` and `historySection` as elements.
+
 ## DataImportPage
 
 | prop | type | meaning |
 |---|---|---|
 | `onInspect` | `(filePath, file) => Promise<{ format, parts?, checks? }>` | **Required.** Say what an uploaded file contains. `parts` holds, for example, an Excel workbook's sheet names. `checks` says what is wrong with a part before it is loaded — see below. |
-| `onCommit` | `(filePath, [{ part, target, fixes }], { originalName }) => Promise<{ results } \| results[]>` | **Required.** Load the included parts into their targets. `fixes` is the person's choice for each fix the checks offered. |
+| `onCommit` | `(filePath, [{ part, target, mode, fixes }], { originalName }) => Promise<{ results } \| results[]>` | **Required.** Load the included parts into their targets. `mode` is `'new'`, `'append'` or `'replace'`; `fixes` is the person's choice for each fix the checks offered. |
+| `onCheckTarget` | `(filePath, { part, target }) => Promise<{ exists, matched, extra, missing: [{ name, required }] } \| null>` | Optional. The part's columns against the table it names, asked as the person types (after a 400 ms pause). Without it nothing is checked and nothing blocked. A new function (another database chosen) asks again. |
 | `accept` | `string` | The file input's `accept` attribute, for example `'.csv,.json,.xlsx,.xls'` |
 | `targetLabel` | `string` | Placeholder for the target name (default `'Target'`) |
+| `onUpload` | `(file, onProgress(percent)) => Promise<{ filePath }>` | Optional: where the file goes (default `uploadFile()` to `configureUpload`'s url). While it uploads, the page shows "Uploading the file… N%" |
 | `onLoadDropped`, `onDownloadDropped` | see [Dropped rows](#dropped-rows) | A result with `dropped > 0` and a `jobId` then says "N dropped — View" |
 
 The file is sent through this package's own `uploadFile()` to the URL set by `configureUpload`, not through a prop. That keeps the component free of app-specific upload wiring. The apps point it at `@xeplr/base-apis`' generic upload route. The upload response must include `filePath`. With `parts`, each part becomes a row (included by default) whose target is `sanitizeTargetName(part)`. Without `parts`, there is one row named after the file. Result rows show `target (part)` and then `rows` + " rows", "Done", or `error`, depending on `success`.
 
 **Checks, before anything is loaded.** `onInspect` may return `checks: { [part]: [{ key, message, fixLabel?, fixDefault?, examples? }] }` (the key `''` for a one-unit file). Each shows under its part as a warning with its message and examples. One with a `fixLabel` offers the fix as a checkbox, on unless `fixDefault: false`; the choice reaches `onCommit` as `fixes[key]`. A result row's `note` is shown under it — what a fix did. The component knows no particular check: the app decides what to look for and what its fix means (BI: rows pasted into one cell, recovered).
 
+**After an import** its mapping clears, because the app has removed the file, and its results stay on screen. The file input is cleared on each click, so choosing the same file again (fixed and saved under its old name) is a new pick.
+
+**New table, Append, Replace.** Each part has a mode, **New table** by default — adding to or emptying a table someone typed the name of is chosen, not assumed. With `onCheckTarget`, what the import will do is said under the part before anything loads (`targetProblems(target, mode, check)`, levels `error` / `warning` / `info` / `ok`):
+
+| mode | the table | said |
+|---|---|---|
+| New table | not there | "A new table … will be created" |
+| New table | there | **error**: "already exists. Choose Append … or Replace …, or type a new name" |
+| Append, Replace | not there | **error**: "There is no table …. Check the name, or choose New table" |
+| Append, Replace | there | file columns the table lacks: **error** (refused); table columns the file lacks: **error** when required (no empty value, no default — every row would be refused), else "left empty"; all matching: "All N columns match" |
+| Replace | there | also a **warning**: it removes every row now in the table, and cannot be rolled back |
+
+An `error` disables Import (`blocked`), as does an empty target or a check still running ("Checking the table…"). The person types the table's name; there is deliberately no list of the database's tables to pick from.
+
 `sanitizeTargetName('Sales 2024.xlsx')` returns `'sales_2024'`. It lowercases, drops the extension, turns runs of non-`[a-z0-9_]` characters into `_`, trims `_` from both ends, and falls back to `'table'`.
 
 ## ImportHistoryPage
@@ -317,7 +362,7 @@ The file is sent through this package's own `uploadFile()` to the URL set by `co
 | `onDelete` | `(job) => Promise` | Removes a history record. The Delete button is on every row, so without this prop it fails with an error. |
 | `onLoadDropped`, `onDownloadDropped` | see [Dropped rows](#dropped-rows) | A job with `rowsDropped > 0` gets a **View dropped** action |
 
-Job shape: `{ id, originalFileName, part, target, rows, status: 'completed' | 'failed' | 'rolled-back', startedAt, error, destination?, rowsLoaded?, rowsDropped?, createdByName? }`. Missing optional fields show "—". Both actions ask first with `raiseConfirm` (danger style). The Delete prompt warns that deleting a completed job's record does **not** undo its data and makes it impossible to roll back. The table shows 20 rows per page.
+Job shape: `{ id, originalFileName, part, target, rows, status: 'completed' | 'failed' | 'rolled-back', startedAt, error, destination?, rowsLoaded?, rowsDropped?, mode?, createdByName? }`. `mode` shows beside the target (Replace highlighted), and **a Replace has no Rollback** (`canRollback(job)`): its old rows are gone. Missing optional fields show "—". Both actions ask first with `raiseConfirm` (danger style). The Delete prompt warns that deleting a completed job's record does **not** undo its data and makes it impossible to roll back. The table shows 20 rows per page.
 
 ## Dropped rows
 
@@ -468,6 +513,7 @@ These create their own DOM nodes with inline styles, so they need no provider, m
 | `NUMBER_FIELD_RULES` | `input[inputmode="decimal"]` or `input.xeplr-numberfield-input` |
 | `TEXT_FIELD_RULES` | a text or search input, a `textarea`, or `.xeplr-textfield-input` |
 | `FILE_UPLOAD_RULES` | `input[type="file"]`; `.xeplr-upload-dropzone` or `[role="dropzone"]`; a `button` |
+| `IMPORTS_RULES` | `#xeplr-imports-connection`, `#xeplr-imports-database` |
 | `DATA_IMPORT_RULES` | `input[type="file"]` |
 | `GRID_DISPLAYER_RULES` | `.xeplr-grid-search`; `.xeplr-grid` |
 | `COLOR_PICKER_RULES` | `.xeplr-colorpicker-swatch` or `[role="option"]` |
@@ -547,6 +593,8 @@ npm test
 
 This runs each `test/*.test.js` with plain `node` and stops at the first failing file. The tests cover the date range model, the range field model, the text field model with `inputStyleVars`, the colour, expander and settings-tree models, and the design rules of the date range, colour picker, expanders and settings tree. CI runs the same files with `node --test` and coverage.
 
+`test/importsApi.test.js` runs the imports model against the real `@xeplr/imports` router: a real Express app, real Postgres and a throwaway `xeplr_configs`. It runs when `PG_HOST`, `PG_PORT`, `PG_USER`, `PG_PASSWORD` and `PG_DATABASE` are set and `XEPLR_IMPORTS_DIR` names the package's folder; otherwise it is skipped. The upload itself uses XMLHttpRequest, so it only runs in a browser, where BI's screen is driven.
+
 ## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xeplr/ui-utils",
-  "version": "1.0.11",
+  "version": "1.0.12",
   "description": "UI utility components: file upload with progress, snackbar, static data (countries/states)",
   "type": "module",
   "main": "src/index.js",

package/src/dataImport/dataImport.js

@@ -35,7 +35,7 @@ function initialFixes(inspectResult, part) {
 }
 
 // inspectResult: { filePath, format, originalName?, parts?: string[], checks? }
-// -> [{ part: string|null, target: string, include: boolean, fixes: { [key]: boolean } }]
+// -> [{ part: string|null, target: string, include: boolean, mode, fixes: { [key]: boolean } }]
 //
 // parts present (e.g. Excel sheets) -> one row per part, all included by
 // default. parts absent (e.g. CSV/JSON — the whole file is one unit) -> a
@@ -43,8 +43,88 @@ function initialFixes(inspectResult, part) {
 export function buildInitialMappings(inspectResult) {
   if (inspectResult.parts && inspectResult.parts.length) {
     return inspectResult.parts.map(function(part) {
-      return { part: part, target: sanitizeTargetName(part), include: true, fixes: initialFixes(inspectResult, part) };
+      return { part: part, target: sanitizeTargetName(part), include: true, mode: DEFAULT_MODE, fixes: initialFixes(inspectResult, part) };
     });
   }
-  return [{ part: null, target: sanitizeTargetName(inspectResult.originalName || 'data'), include: true, fixes: initialFixes(inspectResult, null) }];
+  return [{ part: null, target: sanitizeTargetName(inspectResult.originalName || 'data'), include: true, mode: DEFAULT_MODE, fixes: initialFixes(inspectResult, null) }];
+}
+
+// ── What the import does to its target ──────────────────────────────────
+//
+// New table: it must not exist yet. Append: add to one that exists. Replace:
+// empty one that exists and load the file — the app makes that safe (BI
+// stages it, so a failed import leaves the table as it was) and it cannot be
+// rolled back. New is the default: adding to or emptying a table someone
+// typed the name of is something they choose, not something that happens.
+export var IMPORT_MODES = [
+  { key: 'new', label: 'New table' },
+  { key: 'append', label: 'Append' },
+  { key: 'replace', label: 'Replace' }
+];
+export var DEFAULT_MODE = 'new';
+
+/**
+ * What will happen to the target, said before anything is loaded, from the
+ * app's comparison of the file with the table (onCheckTarget):
+ *   check = { exists, matched: string[], extra: string[], missing: [{ name, required }] }
+ *
+ * @returns {[{ level: 'error'|'warning'|'info'|'ok', message }]} — an 'error'
+ *          blocks the import.
+ */
+export function targetProblems(target, mode, check) {
+  if (!check) return [];
+  var name = '"' + target + '"';
+  var out = [];
+  if (!check.exists) {
+    if (mode === 'new') return [{ level: 'info', message: 'A new table ' + name + ' will be created from the file.' }];
+    return [{ level: 'error', message: 'There is no table ' + name + '. Check the name, or choose New table.' }];
+  }
+  if (mode === 'new') {
+    return [{ level: 'error', message: 'Table ' + name + ' already exists. Choose Append to add to it or Replace to replace its rows, or type a new name.' }];
+  }
+  var extra = check.extra || [];
+  var missing = check.missing || [];
+  var required = missing.filter(function(m) { return m.required; });
+  var optional = missing.filter(function(m) { return !m.required; });
+  if (extra.length) {
+    out.push({ level: 'error', message: 'The file has ' + countOf(extra.length, 'column') + ' the table does not: ' + listOf(extra) +
+      '. The import would be refused — rename or remove ' + (extra.length === 1 ? 'it' : 'them') + ' in the file.' });
+  }
+  if (required.length) {
+    out.push({ level: 'error', message: 'The table needs ' + listOf(required.map(nameOf)) + ', which the file does not have — every row would be refused.' });
+  }
+  if (optional.length) {
+    out.push({ level: 'info', message: 'The table has ' + listOf(optional.map(nameOf)) + ', which the file does not — ' +
+      (optional.length === 1 ? 'it' : 'they') + ' will be left empty.' });
+  }
+  if (!extra.length && !missing.length) {
+    out.push({ level: 'ok', message: 'All ' + countOf((check.matched || []).length, 'column') + ' match the table.' });
+  }
+  if (mode === 'replace') {
+    out.push({ level: 'warning', message: 'Replace removes every row now in ' + name + ' and puts the file\'s rows in their place. It cannot be rolled back.' });
+  }
+  return out;
+}
+
+/** Whether these problems stop the import. */
+export function blocksImport(problems) {
+  return (problems || []).some(function(p) { return p.level === 'error'; });
+}
+
+/** Whether a past import can be undone: a Replace cannot — its old rows are gone. */
+export function canRollback(job) {
+  return !!job && job.status === 'completed' && job.mode !== 'replace';
+}
+
+/** The words for a mode, for a history row: 'Replace', 'Append', 'New table'. */
+export function modeLabel(mode) {
+  var m = IMPORT_MODES.filter(function(x) { return x.key === mode; })[0];
+  return m ? m.label : '';
+}
+
+function nameOf(m) { return m.name; }
+function countOf(n, word) { return n + ' ' + word + (n === 1 ? '' : 's'); }
+function listOf(names) {
+  var shown = names.slice(0, 6).map(function(n) { return '"' + n + '"'; }).join(', ');
+  return names.length > 6 ? shown + ' and ' + (names.length - 6) + ' more' : shown;
 }

package/src/dataImport/designs/DataImportSample.jsx

@@ -1,18 +1,25 @@
 import './dataImport.css';
 
 export default function DataImportSample({
-  file, inspecting, inspected, mappings, committing, results, error,
+  file, inspecting, uploadPercent, inspected, mappings, committing, results, error,
   handleFileChange, updateMapping, setFix, checksOf, handleCommit, reset, accept, targetLabel,
-  canViewDropped, viewDropped
+  canViewDropped, viewDropped, modes, setMode, problems, checking, blocked
 }) {
   return (
     <div className="xeplr-data-import">
       <label className="xeplr-data-import-dropzone">
-        <input type="file" accept={accept} onChange={handleFileChange} />
+        {/* Cleared on each pick, so choosing the same file again — fixed and
+            saved under its old name — is a new pick, not nothing. */}
+        <input type="file" accept={accept} onChange={handleFileChange}
+          onClick={function(e) { e.currentTarget.value = ''; }} />
         {file ? file.name : 'Choose a file to import'}
       </label>
 
-      {inspecting && <p className="xeplr-data-import-hint">Inspecting file…</p>}
+      {inspecting && (
+        <p className="xeplr-data-import-hint">
+          {uploadPercent != null && uploadPercent < 100 ? 'Uploading the file… ' + uploadPercent + '%' : 'Inspecting file…'}
+        </p>
+      )}
       {error && <div className="xeplr-data-import-alert xeplr-data-import-alert-error">{error}</div>}
 
       {inspected && mappings.length > 0 && (
@@ -38,6 +45,30 @@ export default function DataImportSample({
                   onChange={function(e) { updateMapping(i, { target: e.target.value }); }}
                   placeholder={targetLabel}
                 />
+                {/* What the import does to the table: make it, add to it, or
+                    replace its rows. */}
+                {modes && (
+                  <div className="xeplr-data-import-mode" role="radiogroup" aria-label="What to do with the table">
+                    {modes.map(function(mode) {
+                      var on = m.mode === mode.key;
+                      return (
+                        <button key={mode.key} type="button" role="radio" aria-checked={on} disabled={!m.include}
+                          className={'xeplr-data-import-mode-option' + (on ? ' xeplr-data-import-mode-option-on' : '')}
+                          onClick={function() { setMode(i, mode.key); }}>
+                          {mode.label}
+                        </button>
+                      );
+                    })}
+                  </div>
+                )}
+                {/* What will happen to that table, said before anything loads. */}
+                {problems && (problems[i] || []).length > 0 && (
+                  <ul className="xeplr-data-import-target">
+                    {problems[i].map(function(p, pi) {
+                      return <li key={pi} className={'xeplr-data-import-target-' + p.level}>{p.message}</li>;
+                    })}
+                  </ul>
+                )}
                 {/* What the inspect step found, before anything is loaded —
                     and the fix, when one is offered, as a choice. */}
                 {(checksOf ? checksOf(m.part) : []).map(function(c) {
@@ -71,8 +102,9 @@ export default function DataImportSample({
 
       {inspected && mappings.length > 0 && (
         <div className="xeplr-data-import-actions">
-          <button type="button" onClick={handleCommit} disabled={committing || !mappings.some(function(m) { return m.include; })}>
-            {committing ? 'Importing…' : 'Import'}
+          <button type="button" onClick={handleCommit}
+            disabled={committing || checking || blocked || !mappings.some(function(m) { return m.include; })}>
+            {committing ? 'Importing…' : checking ? 'Checking the table…' : 'Import'}
           </button>
           <button type="button" onClick={reset} disabled={committing}>Cancel</button>
         </div>

package/src/dataImport/designs/ImportHistorySample.jsx

@@ -1,6 +1,7 @@
 import './dataImport.css';
 import { XeplrTable } from '@xeplr/ui-table';
 import { raiseConfirm } from '../../confirm/confirm.js';
+import { canRollback, modeLabel } from '../dataImport.js';
 
 var STATUS_LABEL = {
   completed: 'Completed',
@@ -31,7 +32,21 @@ var SCHEMA = {
         header: 'Destination',
         cell: function(info) { return info.getValue() || '—'; }
       },
-      { accessor: 'target', header: 'Target' },
+      {
+        accessor: 'target',
+        header: 'Target',
+        // How it went in: a Replace is worth seeing at a glance — it is the
+        // one import that cannot be rolled back.
+        cell: function(info) {
+          var job = info.row.original;
+          return (
+            <span>
+              {info.getValue()}
+              {job.mode && <span className={'xeplr-import-history-mode xeplr-import-history-mode-' + job.mode}>{modeLabel(job.mode)}</span>}
+            </span>
+          );
+        }
+      },
       {
         accessor: 'rows',
         header: 'Rows',
@@ -107,7 +122,8 @@ export default function ImportHistorySample({ jobs, loading, error, rollingBackI
       key: 'rollback',
       label: 'Rollback',
       variant: 'danger',
-      visible: function(job) { return job.status === 'completed'; },
+      // A Replace cannot be undone: its old rows are gone.
+      visible: function(job) { return canRollback(job); },
       disabled: function(job) { return rollingBackId === job.id; },
       onClick: onRollbackClick
     },

package/src/dataImport/designs/dataImport.css

@@ -162,3 +162,48 @@
 .xeplr-data-import-dropped-actions { display: flex; align-items: center; gap: 8px; }
 .xeplr-data-import-dropped-spacer { flex: 1; }
 .xeplr-data-import-result-dropped { color: var(--xeplr-text-secondary, #999); font-size: 13px; }
+
+/* ── What the import does to its table, and what that will mean ── */
+.xeplr-data-import-mapping-row { flex-wrap: wrap; }
+.xeplr-data-import-mode {
+  display: inline-flex;
+  border: 1px solid var(--xeplr-border-primary, #444);
+  border-radius: 6px;
+  overflow: hidden;
+}
+.xeplr-data-import-mode-option {
+  padding: 6px 12px;
+  border: none;
+  border-right: 1px solid var(--xeplr-border-primary, #444);
+  background: var(--xeplr-bg-secondary, #232323);
+  color: var(--xeplr-text-secondary, #999);
+  font-size: 13px;
+  cursor: pointer;
+}
+.xeplr-data-import-mode-option:last-child { border-right: none; }
+.xeplr-data-import-mode-option-on { background: var(--xeplr-accent, #646cff); color: var(--xeplr-accent-text, #fff); }
+.xeplr-data-import-mode-option:disabled { opacity: 0.5; cursor: default; }
+.xeplr-data-import-target {
+  flex-basis: 100%;
+  margin: 2px 0 0;
+  padding: 0;
+  list-style: none;
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  font-size: 13px;
+}
+.xeplr-data-import-target li { padding: 6px 10px; border-radius: 6px; border: 1px solid transparent; }
+.xeplr-data-import-target-error { color: var(--xeplr-danger, #ff6b6b); background: var(--xeplr-danger-bg, #3d1111); border-color: var(--xeplr-danger-border, #5a1a1a); }
+.xeplr-data-import-target-warning { color: var(--xeplr-warning, #a86a00); background: var(--xeplr-warning-bg, rgba(168, 106, 0, 0.08)); border-color: var(--xeplr-warning, #a86a00); }
+.xeplr-data-import-target-info { color: var(--xeplr-text-secondary, #999); background: var(--xeplr-bg-secondary, #222); }
+.xeplr-data-import-target-ok { color: var(--xeplr-success, #6bcc6b); }
+.xeplr-import-history-mode {
+  margin-left: 6px;
+  padding: 1px 6px;
+  border-radius: 4px;
+  font-size: 11px;
+  background: var(--xeplr-bg-secondary, #222);
+  color: var(--xeplr-text-secondary, #999);
+}
+.xeplr-import-history-mode-replace { color: var(--xeplr-warning, #a86a00); background: var(--xeplr-warning-bg, rgba(168, 106, 0, 0.08)); }

package/src/dataImport/useDataImportController.js

@@ -1,6 +1,6 @@
-import { useState } from 'react';
+import { useEffect, useState } from 'react';
 import { uploadFile } from '../fileUpload/uploadFile.js';
-import { buildInitialMappings, checksFor } from './dataImport.js';
+import { buildInitialMappings, checksFor, targetProblems, blocksImport, IMPORT_MODES } from './dataImport.js';
 
 /**
  * @param {object} options
@@ -10,7 +10,7 @@ import { buildInitialMappings, checksFor } from './dataImport.js';
  *   - required. App-supplied: given a file ALREADY uploaded (see below), what
  *     does it contain? (format, and for a multi-part file like an Excel
  *     workbook, its part/sheet names).
- * @param {(filePath: string, mappings: {part: string|null, target: string, fixes: object}[], meta: {originalName: string}) => Promise<{results: object[]}>} options.onCommit
+ * @param {(filePath: string, mappings: {part: string|null, target: string, mode: string, fixes: object}[], meta: {originalName: string}) => Promise<{results: object[]}>} options.onCommit
  *   (each mapping's `fixes` is the person's choice for each fix the inspect
  *   step's `checks` offered — see checksFor in dataImport.js)
  *   - required. App-supplied: load the included parts into their targets.
@@ -18,6 +18,16 @@ import { buildInitialMappings, checksFor } from './dataImport.js';
  *     path) — pass it through if the app wants it recorded (e.g. import
  *     history), it's otherwise unused by this controller.
  *
+ * @param {(filePath: string, target: {part: string|null, target: string}) => Promise<{exists, matched, extra, missing}>} [options.onCheckTarget]
+ *   - optional. App-supplied: the part's columns against the table it names —
+ *     asked as the person types, so what will happen (refused, columns left
+ *     empty, a table that already exists) is said before anything is loaded.
+ *     Without it no check is made and nothing is blocked.
+ *
+ * @param {(file: File, onProgress: (percent) => void) => Promise<{filePath}>} [options.onUpload]
+ *   - optional: send the file somewhere other than configureUpload's url
+ *     (ImportsPage sends it to @xeplr/imports' /files). Default uploadFile().
+ *
  * The actual file transfer is NOT app-supplied — handleFileChange sends the
  * picked file through @xeplr/ui-utils' own uploadFile() (see
  * fileUpload/uploadFile.js), which every app configures ONCE via
@@ -30,13 +40,30 @@ import { buildInitialMappings, checksFor } from './dataImport.js';
 export function useDataImportController(options = {}) {
   var [file, setFile] = useState(null);
   var [inspecting, setInspecting] = useState(false);
+  // How much of the file has gone up, 0–100 — a 300 MB file takes a while.
+  var [uploadPercent, setUploadPercent] = useState(null);
   var [inspected, setInspected] = useState(null);
   var [mappings, setMappings] = useState([]);
   var [committing, setCommitting] = useState(false);
   var [results, setResults] = useState(null);
   var [error, setError] = useState('');
+  // The app's comparison of each part with the table it names, by
+  // part + target: { loading, result, error }. The mode is not part of the
+  // key — switching it changes what is said, not what the table is.
+  // Kept with the onCheckTarget that answered: a new one (another database,
+  // say) means a new question, and the old answers no longer apply.
+  var [checkStore, setCheckStore] = useState({ by: null, map: {} });
+  var onCheckTarget = options.onCheckTarget;
+  var targetChecks = checkStore.by === onCheckTarget ? checkStore.map : {};
+  function setTargetChecks(update) {
+    setCheckStore(function(prev) {
+      var map = prev.by === onCheckTarget ? prev.map : {};
+      return { by: onCheckTarget, map: update(map) };
+    });
+  }
 
   function reset() {
+    setCheckStore({ by: null, map: {} });
     setFile(null);
     setInspected(null);
     setMappings([]);
@@ -51,7 +78,11 @@ export function useDataImportController(options = {}) {
     setFile(picked);
     setInspecting(true);
     try {
-      var uploadRes = await uploadFile(picked);
+      setUploadPercent(0);
+      var uploadRes = options.onUpload
+        ? await options.onUpload(picked, setUploadPercent)
+        : await uploadFile(picked, { onProgress: setUploadPercent });
+      setUploadPercent(null);
       var inspectRes = await options.onInspect(uploadRes.filePath, picked);
       var merged = Object.assign({ filePath: uploadRes.filePath, originalName: picked.name }, inspectRes);
       setInspected(merged);
@@ -59,6 +90,7 @@ export function useDataImportController(options = {}) {
     } catch (err) {
       setError(err.message || 'Failed to upload/inspect file');
     } finally {
+      setUploadPercent(null);
       setInspecting(false);
     }
   }
@@ -80,15 +112,52 @@ export function useDataImportController(options = {}) {
     });
   }
 
+  // ASKED AS THE PERSON TYPES, once they pause: every included part whose
+  // part + target has not been checked yet. Each answer is kept under its own
+  // part + target, so one that arrives late lands where it belongs.
+  var checkKey = mappings.map(function(m) { return m.include ? keyOf(m) : ''; }).join('\u0001');
+  useEffect(function() {
+    if (!onCheckTarget || !inspected) return undefined;
+    var wanted = mappings.filter(function(m) { return m.include && String(m.target || '').trim() && !targetChecks[keyOf(m)]; });
+    if (!wanted.length) return undefined;
+    var timer = setTimeout(function() {
+      wanted.forEach(function(m) {
+        var key = keyOf(m);
+        setTargetChecks(function(prev) { return Object.assign({}, prev, { [key]: { loading: true } }); });
+        Promise.resolve(onCheckTarget(inspected.filePath, { part: m.part, target: String(m.target).trim() })).then(function(result) {
+          setTargetChecks(function(prev) { return Object.assign({}, prev, { [key]: { result: result || null } }); });
+        }, function(err) {
+          setTargetChecks(function(prev) { return Object.assign({}, prev, { [key]: { error: err.message || 'Could not check the table' } }); });
+        });
+      });
+    }, 400);
+    return function() { clearTimeout(timer); };
+  }, [checkKey, inspected, onCheckTarget]);
+
+  // What each part's target will do, said under it: [{ level, message }].
+  var problems = mappings.map(function(m) {
+    var c = targetChecks[keyOf(m)];
+    if (!m.include || !c) return [];
+    if (c.error) return [{ level: 'warning', message: 'Could not check the table: ' + c.error }];
+    return c.result ? targetProblems(String(m.target).trim(), m.mode, c.result) : [];
+  });
+  var checking = mappings.some(function(m) { var c = targetChecks[keyOf(m)]; return m.include && c && c.loading; });
+  var blocked = mappings.some(function(m, i) { return m.include && blocksImport(problems[i]); }) ||
+    mappings.some(function(m) { return m.include && !String(m.target || '').trim(); });
+
   async function handleCommit() {
     var included = mappings.filter(function(m) { return m.include; });
-    if (!inspected || included.length === 0) return;
+    if (!inspected || included.length === 0 || blocked) return;
     setCommitting(true);
     setError('');
     try {
-      var payload = included.map(function(m) { return { part: m.part, target: m.target, fixes: m.fixes || {} }; });
+      var payload = included.map(function(m) { return { part: m.part, target: String(m.target).trim(), mode: m.mode, fixes: m.fixes || {} }; });
       var res = await options.onCommit(inspected.filePath, payload, { originalName: inspected.originalName });
       setResults((res && res.results) || res || []);
+      // The file is gone once imported (the app removes it), so its mapping
+      // goes too: the results stay, and the next import starts from a file.
+      setInspected(null);
+      setMappings([]);
     } catch (err) {
       setError(err.message || 'Import failed');
     } finally {
@@ -97,10 +166,18 @@ export function useDataImportController(options = {}) {
   }
 
   return {
-    file, inspecting, inspected, mappings, committing, results, error,
+    file, inspecting, uploadPercent, inspected, mappings, committing, results, error,
     handleFileChange, updateMapping, setFix, handleCommit, reset,
+    // The import's mode per part, what its target will do, and whether that stops it.
+    modes: IMPORT_MODES,
+    setMode: function(index, mode) { updateMapping(index, { mode: mode }); },
+    problems: problems,
+    checking: checking,
+    blocked: blocked,
     checksOf: function(part) { return checksFor(inspected, part); },
     accept: options.accept,
     targetLabel: options.targetLabel || 'Target'
   };
 }
+
+function keyOf(m) { return (m.part == null ? '' : m.part) + '\u0000' + String(m.target || '').trim(); }

package/src/fileUpload/uploadFile.js

@@ -9,6 +9,16 @@ export function configureUpload(config = {}) {
   if (config.getHeaders) _config.getHeaders = config.getHeaders;
 }
 
+/**
+ * The headers every request to the app's API carries — what configureUpload
+ * was given (getHeaders, called each time so a token is current, or static
+ * headers). Exported so a page calling the app's JSON routes signs them the
+ * same way as its uploads, without a second configuration.
+ */
+export function uploadHeaders() {
+  return Object.assign({}, _config.getHeaders ? _config.getHeaders() : _config.headers);
+}
+
 /**
  * Upload files to the server.
  * @param {File[]} files - Files to upload

package/src/imports/designs/ImportsSample.jsx

@@ -0,0 +1,72 @@
+import { useEffect, useState } from 'react';
+import './imports.css';
+
+/**
+ * The import screen: which database, the import, and the history. Presentation
+ * only — everything comes from useImportsController; the import and history
+ * sections arrive as elements (ImportsPage passes DataImportPage and
+ * ImportHistoryPage), so a custom design can place them anywhere.
+ *
+ * Required (IMPORTS_RULES): #xeplr-imports-connection, #xeplr-imports-database.
+ */
+export default function ImportsSample({
+  targets, targetsError, connectionId, dbInfoId, databases, chooseConnection, chooseDatabase,
+  importing, progressText, stop, importSection, historySection
+}) {
+  return (
+    <div className="xeplr-imports">
+      <section className="xeplr-imports-card">
+        <h2 className="xeplr-imports-title">1. Choose a database</h2>
+        <p className="xeplr-imports-hint">The file is loaded into a table in this database.</p>
+        {targetsError && <div className="xeplr-imports-error">{targetsError}</div>}
+        {!targetsError && targets.length === 0 && <p className="xeplr-imports-hint">There is no database to import into yet.</p>}
+        <div className="xeplr-imports-pickers">
+          <label className="xeplr-imports-field">
+            <span>Connection</span>
+            <select id="xeplr-imports-connection" value={connectionId} disabled={!!importing}
+              onChange={function(e) { chooseConnection(e.target.value); }}>
+              {targets.map(function(t) { return <option key={t.connectionId} value={t.connectionId}>{t.label}</option>; })}
+            </select>
+          </label>
+          <label className="xeplr-imports-field">
+            <span>Database</span>
+            <select id="xeplr-imports-database" value={dbInfoId} disabled={!!importing}
+              onChange={function(e) { chooseDatabase(e.target.value); }}>
+              {databases.map(function(d) { return <option key={d.id} value={d.id}>{d.label}</option>; })}
+            </select>
+          </label>
+        </div>
+      </section>
+
+      <section className="xeplr-imports-card">
+        <h2 className="xeplr-imports-title">2. Upload &amp; map</h2>
+        <p className="xeplr-imports-hint">Excel files let you load each sheet into its own table.</p>
+        {importing && (
+          <p className="xeplr-imports-progress">
+            {progressText}
+            <RunClock startedAt={importing.startedAt} />
+            <button type="button" className="xeplr-imports-stop" title="Stop this import" onClick={stop}>✕</button>
+          </p>
+        )}
+        {importSection}
+      </section>
+
+      <section className="xeplr-imports-card">
+        <h2 className="xeplr-imports-title">Import history</h2>
+        <p className="xeplr-imports-hint">Past imports — roll one back if it loaded the wrong data, see the rows it dropped, or delete the record.</p>
+        {historySection}
+      </section>
+    </div>
+  );
+}
+
+/** "12 s", "3 min 4 s" — how long the import has been running. */
+function RunClock({ startedAt }) {
+  var [now, setNow] = useState(Date.now());
+  useEffect(function() {
+    var t = setInterval(function() { setNow(Date.now()); }, 1000);
+    return function() { clearInterval(t); };
+  }, []);
+  var s = Math.max(0, Math.round((now - startedAt) / 1000));
+  return <span className="xeplr-imports-clock">{s < 60 ? s + ' s' : Math.floor(s / 60) + ' min ' + (s % 60) + ' s'}</span>;
+}

package/src/imports/designs/imports.css

@@ -0,0 +1,29 @@
+/* Uses @xeplr/ui-account's --xeplr-* theme tokens when available, with the
+   same dark fallbacks as dataImport.css. */
+.xeplr-imports { display: flex; flex-direction: column; gap: 20px; color: var(--xeplr-text-primary, #e0e0e0); }
+.xeplr-imports-card {
+  padding: 20px;
+  border: 1px solid var(--xeplr-border-secondary, #2a2a2a);
+  border-radius: 12px;
+  background: var(--xeplr-bg-primary, #1a1a1a);
+}
+.xeplr-imports-title { margin: 0 0 4px; font-size: 18px; font-weight: 600; }
+.xeplr-imports-hint { margin: 0 0 14px; font-size: 13px; color: var(--xeplr-text-secondary, #999); }
+.xeplr-imports-error {
+  margin-bottom: 12px; padding: 10px 12px; border-radius: 6px; font-size: 13px;
+  background: var(--xeplr-danger-bg, #3d1111); color: var(--xeplr-danger, #ff6b6b); border: 1px solid var(--xeplr-danger-border, #5a1a1a);
+}
+.xeplr-imports-pickers { display: grid; grid-template-columns: repeat(auto-fit, minmax(220px, 1fr)); gap: 12px; }
+.xeplr-imports-field { display: flex; flex-direction: column; gap: 6px; font-size: 13px; color: var(--xeplr-text-secondary, #999); }
+.xeplr-imports-field select {
+  padding: 9px 10px; border-radius: 6px; font-size: 14px; font-family: inherit;
+  border: 1px solid var(--xeplr-border-primary, #444);
+  background: var(--xeplr-bg-secondary, #232323);
+  color: var(--xeplr-text-primary, #e0e0e0);
+}
+.xeplr-imports-progress { display: flex; align-items: center; gap: 10px; margin: 0 0 12px; font-size: 13px; }
+.xeplr-imports-clock { color: var(--xeplr-text-secondary, #999); font-variant-numeric: tabular-nums; }
+.xeplr-imports-stop {
+  padding: 2px 8px; border-radius: 4px; cursor: pointer; font-size: 12px;
+  border: 1px solid var(--xeplr-border-primary, #444); background: none; color: var(--xeplr-text-secondary, #999);
+}

package/src/imports/designs/index.js

@@ -0,0 +1 @@
+export { default as ImportsSample } from './ImportsSample.jsx';

package/src/imports/importsApi.js

@@ -0,0 +1,96 @@
+// IMPORTS — model. The calls @xeplr/imports' routes answer, and the pure
+// helpers the page needs. No React; fetch and XMLHttpRequest only.
+//
+// basePath is where the app mounted the router as the browser sees it —
+// '/imports', or '/api/imports' behind a proxy prefix. Requests carry the
+// headers configureUpload was given (uploadHeaders): sign-in and tenancy.
+
+import { uploadFile, uploadHeaders } from '../fileUpload/uploadFile.js';
+
+/** The import routes under one base path. Every call rejects with the server's own `error`. */
+export function createImportsApi(basePath) {
+  var base = String(basePath || '/imports').replace(/\/+$/, '');
+
+  async function call(method, path, body) {
+    var headers = uploadHeaders();
+    if (body) headers['content-type'] = 'application/json';
+    var res = await fetch(base + path, { method: method, headers: headers, body: body ? JSON.stringify(body) : undefined });
+    var data = await res.json().catch(function() { return {}; });
+    if (!res.ok) throw new Error(data.error || ('The request failed (' + res.status + ')'));
+    return data;
+  }
+
+  return {
+    upload: function(file, onProgress) { return uploadFile(file, { url: base + '/files', onProgress: onProgress }); },
+    inspect: function(filePath) { return call('POST', '/inspect', { filePath: filePath }); },
+    checkTarget: function(body) { return call('POST', '/check-target', body); },
+    commit: function(body) { return call('POST', '/commit', body); },
+    run: function(runId) { return call('GET', '/runs/' + encodeURIComponent(runId)); },
+    stop: function(runId) { return call('POST', '/runs/' + encodeURIComponent(runId) + '/stop'); },
+    targets: async function() { return (await call('GET', '/targets')).dataArray || []; },
+    history: async function() { return (await call('GET', '/history')).dataArray || []; },
+    dropped: function(id) { return call('GET', '/history/' + encodeURIComponent(id) + '/dropped'); },
+    rollback: function(id) { return call('POST', '/history/' + encodeURIComponent(id) + '/rollback'); },
+    remove: function(id) { return call('POST', '/history/' + encodeURIComponent(id) + '/delete'); },
+    /** The dropped rows as a file: { blob, name } — saving it is the page's job. */
+    droppedFile: async function(id) {
+      var res = await fetch(base + '/history/' + encodeURIComponent(id) + '/dropped/file', { headers: uploadHeaders() });
+      if (!res.ok) {
+        var data = await res.json().catch(function() { return {}; });
+        throw new Error(data.error || ('The download failed (' + res.status + ')'));
+      }
+      return { blob: await res.blob(), name: fileNameOf(res.headers.get('content-disposition'), 'dropped rows.xlsx') };
+    }
+  };
+}
+
+/** The file name a Content-Disposition gives — filename* (UTF-8) first. */
+export function fileNameOf(disposition, fallback) {
+  var cd = String(disposition || '');
+  var star = /filename\*=UTF-8''([^;]+)/i.exec(cd);
+  if (star) { try { return decodeURIComponent(star[1]); } catch (e) { /* the plain one */ } }
+  var plain = /filename="([^"]+)"/i.exec(cd);
+  return plain ? plain[1] : fallback;
+}
+
+/** "Sheet 2 of 3 (Orders) · 412,000 rows read · 400,000 written" — how far an import has got. */
+export function importProgressText(p) {
+  if (!p) return 'Importing — reading the file…';
+  var parts = [];
+  if (p.mappings > 1) parts.push('Sheet ' + p.mapping + ' of ' + p.mappings + (p.sheet ? ' (' + p.sheet + ')' : ''));
+  if (p.rowsRead != null) parts.push(Number(p.rowsRead).toLocaleString() + ' rows read');
+  if (p.rowsWritten != null) parts.push(Number(p.rowsWritten).toLocaleString() + ' written');
+  if (p.phase === 'merging') parts.push('replacing the table');
+  return 'Importing · ' + (parts.join(' · ') || 'starting');
+}
+
+/**
+ * A finished run in DataImportPage's result shape, or the error it ended
+ * with. `run` is GET /runs/:id once its status is no longer 'running'.
+ */
+export function runResults(run) {
+  if (run.status === 'error') throw new Error(run.error || 'The import failed');
+  if (run.status === 'stopped') throw new Error(run.error === 'Stopped' || !run.error ? 'The import was stopped.' : run.error);
+  return ((run.result && run.result.results) || []).map(function(r) {
+    return {
+      part: r.sheet, target: r.targetTable, success: r.success, rows: r.rows, error: r.error,
+      dropped: r.dropped || 0, jobId: r.jobId || null,
+      note: r.recovered ? Number(r.recovered).toLocaleString() + ' of them recovered from cells they had been pasted into' : null
+    };
+  });
+}
+
+/** A history row in ImportHistoryPage's shape. */
+export function historyJob(row) {
+  return {
+    id: row.id, originalFileName: row.originalFileName, part: row.part, target: row.targetTable,
+    destination: row.destination, rows: row.totalRows, rowsLoaded: row.rowsLoaded, rowsDropped: row.rowsDropped,
+    mode: row.mode, status: row.status, startedAt: row.startedAt, error: row.errorMessage, createdByName: row.createdByName
+  };
+}
+
+/** The databases of the chosen connection, for the second picker. */
+export function databasesOf(targets, connectionId) {
+  var t = (targets || []).filter(function(x) { return x.connectionId === connectionId; })[0];
+  return (t && t.databases) || [];
+}

package/src/imports/pages.jsx

@@ -0,0 +1,24 @@
+import { useImportsController } from './useImportsController.js';
+import ImportsSample from './designs/ImportsSample.jsx';
+import { IMPORTS_RULES } from './validateDesign.js';
+import { useDesignValidator } from '../dataImport/validateDesign.js';
+import { DataImportPage, ImportHistoryPage } from '../dataImport/pages.jsx';
+
+/**
+ * The whole import feature against @xeplr/imports, ready to route to:
+ *
+ *   <Route path="/upload" element={<ImportsPage basePath="/api/imports" />} />
+ *
+ * Requests carry the headers given to configureUpload (sign-in, tenancy).
+ */
+export function ImportsPage(props) {
+  var c = useImportsController(props);
+  var ref = useDesignValidator('ImportsPage', IMPORTS_RULES);
+  return (
+    <div ref={ref}>
+      <ImportsSample {...c}
+        importSection={<DataImportPage accept=".csv,.json,.xlsx,.xls" targetLabel="Table name" {...c.importProps} />}
+        historySection={<ImportHistoryPage key={c.historyVersion} {...c.historyProps} />} />
+    </div>
+  );
+}

package/src/imports/useImportsController.js

@@ -0,0 +1,125 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { createImportsApi, importProgressText, runResults, historyJob, databasesOf } from './importsApi.js';
+
+/**
+ * The whole import screen against @xeplr/imports' routes: which database,
+ * the import itself (DataImportPage), its progress and ✕, and the history
+ * (ImportHistoryPage) with dropped rows, rollback and delete. No React-free
+ * logic lives here — see importsApi.js.
+ *
+ * @param {object} props
+ * @param {string} [props.basePath='/imports'] - where the app mounted the router, as the browser sees it
+ * @param {number} [props.pollMs=1000] - how often a running import is asked how far it has got
+ */
+export function useImportsController(props = {}) {
+  var api = useMemo(function() { return createImportsApi(props.basePath); }, [props.basePath]);
+  var pollMs = props.pollMs || 1000;
+
+  var [targets, setTargets] = useState([]);
+  var [targetsError, setTargetsError] = useState('');
+  var [connectionId, setConnectionId] = useState('');
+  var [dbInfoId, setDbInfoId] = useState('');
+  // The import running now: { runId, startedAt, progress }.
+  var [importing, setImporting] = useState(null);
+  // Bumped to make the history list read itself again.
+  var [historyVersion, setHistoryVersion] = useState(0);
+  var mounted = useRef(true);
+  useEffect(function() { mounted.current = true; return function() { mounted.current = false; }; }, []);
+
+  useEffect(function() {
+    api.targets().then(function(list) {
+      if (!mounted.current) return;
+      setTargets(list);
+      if (list.length) {
+        setConnectionId(list[0].connectionId);
+        setDbInfoId(((list[0].databases || [])[0] || {}).id || '');
+      }
+    }, function(err) { if (mounted.current) setTargetsError(err.message); });
+  }, [api]);
+
+  function chooseConnection(id) {
+    setConnectionId(id);
+    setDbInfoId((databasesOf(targets, id)[0] || {}).id || '');
+  }
+
+  var onUpload = useCallback(function(file, onProgress) { return api.upload(file, onProgress); }, [api]);
+
+  var onInspect = useCallback(async function(filePath) {
+    var found = await api.inspect(filePath);
+    return { format: found.format, parts: found.sheets, checks: found.checks };
+  }, [api]);
+
+  // Bound to the chosen database, so choosing another asks again.
+  var onCheckTarget = useCallback(function(filePath, part) {
+    if (!connectionId || !dbInfoId) return Promise.resolve(null);
+    return api.checkTarget({ filePath: filePath, sheet: part.part, connectionId: connectionId, dbInfoId: dbInfoId, targetTable: part.target });
+  }, [api, connectionId, dbInfoId]);
+
+  // STARTS the import, then asks how far it has got until it ends. The
+  // request answers at once with a run id, so no gateway timeout applies.
+  var onCommit = useCallback(async function(filePath, mappings, meta) {
+    if (!connectionId || !dbInfoId) throw new Error('Choose a database to import into first');
+    var started = await api.commit({
+      filePath: filePath, connectionId: connectionId, dbInfoId: dbInfoId, originalFileName: meta && meta.originalName,
+      mappings: mappings.map(function(m) {
+        return { sheet: m.part, targetTable: m.target, mode: m.mode, repairPastedRows: Boolean(m.fixes && m.fixes.pastedRows) };
+      })
+    });
+    setImporting({ runId: started.runId, startedAt: Date.now(), progress: null });
+    setHistoryVersion(function(v) { return v + 1; });   // in the history from its first row
+    try {
+      for (;;) {
+        await new Promise(function(r) { setTimeout(r, pollMs); });
+        var run = await api.run(started.runId);
+        if (run.status !== 'running') return { results: runResults(run) };
+        if (mounted.current) setImporting(function(cur) { return cur && cur.runId === run.id ? Object.assign({}, cur, { progress: run.progress }) : cur; });
+      }
+    } finally {
+      if (mounted.current) {
+        setImporting(null);
+        setHistoryVersion(function(v) { return v + 1; });
+      }
+    }
+  }, [api, connectionId, dbInfoId, pollMs]);
+
+  function stop() {
+    if (importing) api.stop(importing.runId).catch(function() {});
+  }
+
+  var onList = useCallback(async function() {
+    return { jobs: (await api.history()).map(historyJob) };
+  }, [api]);
+  var onRollback = useCallback(function(job) { return api.rollback(job.id); }, [api]);
+  var onDelete = useCallback(function(job) { return api.remove(job.id); }, [api]);
+  var onLoadDropped = useCallback(function(job) { return api.dropped(job.id); }, [api]);
+  var onDownloadDropped = useCallback(async function(job) {
+    var file = await api.droppedFile(job.id);
+    var url = URL.createObjectURL(file.blob);
+    var a = document.createElement('a');
+    a.href = url;
+    a.download = file.name;
+    document.body.appendChild(a);
+    a.click();
+    a.remove();
+    setTimeout(function() { URL.revokeObjectURL(url); }, 0);
+  }, [api]);
+
+  return {
+    targets: targets,
+    targetsError: targetsError,
+    connectionId: connectionId,
+    dbInfoId: dbInfoId,
+    databases: databasesOf(targets, connectionId),
+    chooseConnection: chooseConnection,
+    chooseDatabase: setDbInfoId,
+    importing: importing,
+    progressText: importing ? importProgressText(importing.progress) : '',
+    stop: stop,
+    historyVersion: historyVersion,
+    // What the two built-in pages take.
+    importProps: { onUpload: onUpload, onInspect: onInspect, onCheckTarget: onCheckTarget, onCommit: onCommit,
+      onLoadDropped: onLoadDropped, onDownloadDropped: onDownloadDropped },
+    historyProps: { onList: onList, onRollback: onRollback, onDelete: onDelete,
+      onLoadDropped: onLoadDropped, onDownloadDropped: onDownloadDropped }
+  };
+}

package/src/imports/validateDesign.js

@@ -0,0 +1,6 @@
+// What an ImportsPage design must have: the two pickers that say where the
+// file goes. (The import and history sections validate themselves.)
+export var IMPORTS_RULES = [
+  { id: 'xeplr-imports-connection', label: 'Connection picker' },
+  { id: 'xeplr-imports-database', label: 'Database picker' }
+];

package/src/index.js

@@ -17,7 +17,7 @@ export { FileUploadPage } from './fileUpload/pages.jsx';
 // the whole file, for CSV/JSON) to app-defined named targets, commit. The
 // app supplies onInspect/onCommit (its own upload + load endpoints); this
 // module only owns the file-pick -> mapping -> commit flow and UI.
-export { sanitizeTargetName, buildInitialMappings } from './dataImport/dataImport.js';
+export { sanitizeTargetName, buildInitialMappings, IMPORT_MODES, DEFAULT_MODE, targetProblems, blocksImport, canRollback, modeLabel } from './dataImport/dataImport.js';
 
 // DataImport — controller
 export { useDataImportController } from './dataImport/useDataImportController.js';
@@ -50,6 +50,16 @@ export { DROPPED_ROWS_RULES } from './dataImport/validateDesign.js';
 export { DroppedRowsSample } from './dataImport/designs/index.js';
 export { DroppedRowsPage } from './dataImport/pages.jsx';
 
+// Imports — the whole import screen against @xeplr/imports' routes: database
+// picker, import (DataImportPage), progress with ✕, history (ImportHistoryPage).
+// <ImportsPage basePath="/api/imports" /> is all an app adds.
+export { createImportsApi, importProgressText, runResults, historyJob, databasesOf, fileNameOf } from './imports/importsApi.js';
+export { useImportsController } from './imports/useImportsController.js';
+export { IMPORTS_RULES } from './imports/validateDesign.js';
+export { ImportsSample } from './imports/designs/index.js';
+export { ImportsPage } from './imports/pages.jsx';
+export { uploadHeaders } from './fileUpload/uploadFile.js';
+
 // NumberField — model
 export {
   NUMBER_TYPES,