@xeplr/ui-utils 1.0.10 → 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`, 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,15 +97,17 @@ 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 |
 | `GridDisplayerPage` | [see below](#griddisplayerpage) | Searchable, sortable grid of tiles you render |
 | `ColorPickerPage` | [see below](#colorpickerpage) | Swatches, no colour, a custom colour, opacity and a live preview, as one CSS colour |
 | `ExpandersPage` | [see below](#panel-panelsection-panelfield-expanderspage) | Titled parts of a panel, one open at a time |
 | `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`, `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)
 
@@ -118,8 +120,10 @@ 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` |
 | `useColorPickerController(props)` | ColorPickerPage props | `label, value, hex, opacity, swatches [{color, selected}], custom, allowNone, allowOpacity, previewText, pick(hex), setOpacity(0–100), clear` |
 | `useExpandersController(props)` | ExpandersPage props | `items` (each with `open`), `toggle(key)` |
@@ -165,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`, `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
 
@@ -290,19 +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
@@ -312,8 +360,22 @@ The file is sent through this package's own `uploadFile()` to the URL set by `co
 | `onList` | `() => Promise<{ jobs } \| jobs[]>` | **Required, and must be a stable function**: module-level, or wrapped in `useCallback`. The list reloads whenever its identity changes. |
 | `onRollback` | `(job) => Promise` | Rollback of a `completed` job. The list reloads afterwards. |
 | `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?, 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
 
-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.
+Rows an import's database refused (a constraint, a value its column will not take) are not in the table. Without a way to see them, "63 dropped" is a number nobody can act on. `DataImportPage` and `ImportHistoryPage` show them when the app passes:
+
+| prop | type | meaning |
+|---|---|---|
+| `onLoadDropped` | `(job) => Promise<{ columns, rows: [{ rowNum, reason, values }], total, dropped }>` | The dropped rows of one import. `columns` are the file's, in order; `values` is keyed by them; `total` is how many were kept, `dropped` how many the import counted. Without this prop nothing offers to show them. |
+| `onDownloadDropped` | `(job) => Promise` | Saves them as a file. Make it one that imports again as it is: the file's columns only, header in row 1 (BI: an .xlsx). |
+
+`job` is a history row (`rowsDropped`), or an import result (`{ id: result.jobId, dropped }`). The dialog shows the heading ("2 rows dropped from stock.csv → stock"), a table of row number, **Why it was dropped** and the file's columns, and **Copy**, **Download Excel**, **Close** (Escape and a click outside close it too). **Copy** puts the file's columns and the rows on the clipboard as tab-separated text, quoted as Excel quotes it, so it pastes into Excel as cells; like the download, it leaves out the row number and reason, so pasted, fixed and saved, it imports again. A note says when not every row is there: an import from before rows were kept (only a count), fewer kept than dropped, or only the first ones shown.
+
+The model (`droppedRows.js`) is pure: `droppedCount(job)`, `droppedTable(data)` (keys `c0`, `c1`, … because a column name may hold a dot), `droppedAsTsv(data)`, `tsvCell(value)`, `droppedSummary(job, data)`.
 
 ## GridDisplayerPage
 
@@ -451,12 +513,14 @@ 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"]` |
 | `EXPANDERS_RULES` | `.xeplr-expander-head` or `[aria-expanded]` |
 | `SETTINGS_TREE_RULES` | `.xeplr-tree-head` or `[aria-expanded]` |
 | `IMPORT_HISTORY_RULES` | nothing |
+| `DROPPED_ROWS_RULES` | `#xeplr-dropped-rows-copy`, `#xeplr-dropped-rows-download`, `#xeplr-dropped-rows-close` — checked when the dialog opens, since it is not on the page before |
 
 ## Theming
 
@@ -529,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.10",
+  "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,17 +1,25 @@
 import './dataImport.css';
 
 export default function DataImportSample({
-  file, inspecting, inspected, mappings, committing, results, error,
-  handleFileChange, updateMapping, setFix, checksOf, handleCommit, reset, accept, targetLabel
+  file, inspecting, uploadPercent, inspected, mappings, committing, results, error,
+  handleFileChange, updateMapping, setFix, checksOf, handleCommit, reset, accept, targetLabel,
+  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 && (
@@ -37,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) {
@@ -70,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>
@@ -87,6 +120,19 @@ export default function DataImportSample({
                   {r.success ? (r.rows != null ? r.rows + ' rows' : 'Done') : (r.error || 'Failed')}
                 </span>
                 {r.note && <span className="xeplr-data-import-result-note">{r.note}</span>}
+                {r.success && r.dropped > 0 && (
+                  <span className="xeplr-data-import-result-dropped">
+                    {r.dropped.toLocaleString()} dropped
+                    {canViewDropped && canViewDropped({ id: r.jobId, dropped: r.dropped }) && (
+                      <>
+                        {' — '}
+                        <button type="button" className="xeplr-data-import-link" onClick={function() {
+                          viewDropped({ id: r.jobId, dropped: r.dropped, originalFileName: file && file.name, part: r.part, target: r.target });
+                        }}>View</button>
+                      </>
+                    )}
+                  </span>
+                )}
               </div>
             );
           })}

package/src/dataImport/designs/DroppedRowsSample.jsx

@@ -0,0 +1,65 @@
+import { useEffect } from 'react';
+import './dataImport.css';
+import { XeplrTable } from '@xeplr/ui-table';
+
+/**
+ * The rows an import dropped, in a dialog: each with its place in the file and
+ * why the database refused it, and Copy / Download to fix and import again.
+ * Presentation only — everything comes from useDroppedRowsController.
+ *
+ * Required (DROPPED_ROWS_RULES): #xeplr-dropped-rows-copy, #xeplr-dropped-rows-download,
+ * #xeplr-dropped-rows-close.
+ */
+export default function DroppedRowsSample({
+  job, table, summary, loading, error, copied, downloading, canCopy, canDownload, copy, download, close
+}) {
+  useEffect(function() {
+    function onKey(e) { if (e.key === 'Escape') close(); }
+    window.addEventListener('keydown', onKey);
+    return function() { window.removeEventListener('keydown', onKey); };
+  }, [close]);
+
+  if (!job) return null;
+  var schema = table ? { 0: { columns: table.columns.map(function(c) {
+    return { accessor: c.key, header: c.header, cell: c.key === 'reason'
+      ? function(info) { return <span className="xeplr-data-import-dropped-reason">{info.getValue()}</span>; }
+      : undefined };
+  }) } } : null;
+
+  return (
+    <div className="xeplr-data-import-dropped-backdrop" onMouseDown={function(e) { if (e.target === e.currentTarget) close(); }}>
+      <div className="xeplr-data-import-dropped" role="dialog" aria-modal="true" aria-label={summary ? summary.heading : 'Dropped rows'}>
+        <div className="xeplr-data-import-dropped-head">
+          <h3 className="xeplr-data-import-dropped-title">{summary && summary.heading}</h3>
+          <p className="xeplr-data-import-hint">
+            The database refused these rows, so they are not in the table. Copy or download them, fix them, and import them again — the
+            file has the same columns as yours.
+          </p>
+        </div>
+
+        {summary && summary.note && <div className="xeplr-data-import-dropped-note">{summary.note}</div>}
+        {error && <div className="xeplr-data-import-alert xeplr-data-import-alert-error">{error}</div>}
+        {loading && <p className="xeplr-data-import-hint">Loading the dropped rows…</p>}
+
+        {table && table.rows.length > 0 && (
+          <div className="xeplr-data-import-dropped-table">
+            <XeplrTable data={table.rows} schema={schema} pageSize={50} />
+          </div>
+        )}
+
+        <div className="xeplr-data-import-dropped-actions">
+          <button id="xeplr-dropped-rows-copy" type="button" className="xeplr-data-import-button"
+            disabled={!canCopy} onClick={copy}>
+            {copied ? 'Copied' : 'Copy'}
+          </button>
+          <button id="xeplr-dropped-rows-download" type="button" className="xeplr-data-import-button xeplr-data-import-button-primary"
+            disabled={!canDownload || downloading} onClick={download}>
+            {downloading ? 'Downloading…' : 'Download Excel'}
+          </button>
+          <span className="xeplr-data-import-dropped-spacer" />
+          <button id="xeplr-dropped-rows-close" type="button" className="xeplr-data-import-button" onClick={close}>Close</button>
+        </div>
+      </div>
+    </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',
@@ -78,7 +93,7 @@ var SCHEMA = {
   }
 };
 
-export default function ImportHistorySample({ jobs, loading, error, rollingBackId, deletingId, handleRollback, handleDelete }) {
+export default function ImportHistorySample({ jobs, loading, error, rollingBackId, deletingId, handleRollback, handleDelete, canViewDropped, viewDropped }) {
   async function onRollbackClick(job) {
     var ok = await raiseConfirm(
       'This deletes every row loaded into "' + job.target + '" by this import. This cannot be undone.',
@@ -96,11 +111,19 @@ export default function ImportHistorySample({ jobs, loading, error, rollingBackI
   }
 
   var rowActions = [
+    {
+      // The rows the database refused: see them, copy or download them.
+      key: 'dropped',
+      label: 'View dropped',
+      visible: function(job) { return !!canViewDropped && canViewDropped(job); },
+      onClick: function(job) { viewDropped(job); }
+    },
     {
       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

@@ -115,3 +115,95 @@
 .xeplr-data-import-check-examples { margin: 6px 0 0; padding-left: 18px; font-size: 12px; color: var(--xeplr-text-muted, #888); }
 .xeplr-data-import-result-note { flex-basis: 100%; font-size: 12px; color: var(--xeplr-text-muted, #888); }
 .xeplr-data-import-result-row { flex-wrap: wrap; }
+
+/* ── Dropped rows: the rows an import's database refused, in a dialog ── */
+.xeplr-data-import-button {
+  padding: 7px 14px;
+  border-radius: 6px;
+  border: 1px solid var(--xeplr-border-primary, #444);
+  background: var(--xeplr-bg-secondary, #232323);
+  color: var(--xeplr-text-primary, #e0e0e0);
+  font-size: 13px;
+  cursor: pointer;
+}
+.xeplr-data-import-button-primary { border-color: transparent; background: var(--xeplr-accent, #646cff); color: var(--xeplr-accent-text, #fff); }
+.xeplr-data-import-button:disabled { opacity: 0.6; cursor: default; }
+.xeplr-data-import-link {
+  padding: 0; border: none; background: none; cursor: pointer;
+  color: var(--xeplr-accent, #646cff); font-size: inherit; text-decoration: underline;
+}
+
+.xeplr-data-import-dropped-backdrop {
+  position: fixed; inset: 0; z-index: 1000;
+  display: flex; align-items: center; justify-content: center;
+  padding: 24px;
+  background: rgba(0, 0, 0, 0.55);
+}
+.xeplr-data-import-dropped {
+  display: flex; flex-direction: column; gap: 12px;
+  width: min(1100px, 100%); max-height: calc(100vh - 48px);
+  padding: 20px;
+  border: 1px solid var(--xeplr-border-primary, #444);
+  border-radius: 10px;
+  background: var(--xeplr-bg-primary, #1a1a1a);
+  color: var(--xeplr-text-primary, #e0e0e0);
+  box-shadow: 0 12px 40px rgba(0, 0, 0, 0.4);
+}
+.xeplr-data-import-dropped-head { display: flex; flex-direction: column; gap: 4px; }
+.xeplr-data-import-dropped-title { margin: 0; font-size: 16px; font-weight: 600; }
+.xeplr-data-import-dropped-note {
+  padding: 8px 12px; border-radius: 6px; font-size: 13px;
+  background: var(--xeplr-bg-secondary, #222);
+  border: 1px solid var(--xeplr-border-secondary, #2a2a2a);
+  color: var(--xeplr-text-secondary, #999);
+}
+.xeplr-data-import-dropped-table { flex: 1 1 auto; min-height: 0; overflow: auto; }
+.xeplr-data-import-dropped-reason { color: var(--xeplr-danger, #ff6b6b); white-space: normal; }
+.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/designs/index.js

@@ -1,2 +1,3 @@
 export { default as DataImportSample } from './DataImportSample.jsx';
 export { default as ImportHistorySample } from './ImportHistorySample.jsx';
+export { default as DroppedRowsSample } from './DroppedRowsSample.jsx';