@xeplr/ui-utils 1.0.9 → 1.0.11

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`, `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:
 
    ```js
    import { resolveDateValue } from '@xeplr/ui-utils/src/dateRange/dateRange.js'
@@ -99,13 +99,14 @@ export default function SelectCompany() {
 | `FileUploadPage` | [see below](#fileuploadpage) | Drag-and-drop upload with type and size checks and a progress bar |
 | `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`, `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 +119,9 @@ 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), handleCommit, reset, accept, targetLabel` |
+| `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` |
 | `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)` |
@@ -146,7 +148,7 @@ export default function SelectCompany() {
 | `toggleOpen`, `initialOpen` | `(open, key, multiple?) → keys`, `(items, initial?, multiple?) → keys` | Which expanders are open |
 | `toggleBranch`, `decorateTree` | `(open, parentKey, key) → open`, `(nodes, open) → nodes` | Which branch of a settings tree is open at each level; `open` is `{ [parentKey]: key }`, the root's parent `''` |
 | `filterGridRows`, `sortGridRows` | `(rows, query, fields)`, `(rows, field, 'asc'\|'desc')` | Grid search and sort. An array field matches if any entry matches. |
-| `sanitizeTargetName`, `buildInitialMappings` | `(name) → string`, `({ parts?, originalName? }) → [{ part, target, include }]` | Data import mapping |
+| `sanitizeTargetName`, `buildInitialMappings`, `checksFor` | `(name) → string`, `({ parts?, originalName?, checks? }) → [{ part, target, include, fixes }]`, `(inspectResult, part) → checks[]` | Data import mapping |
 | `configureUpload`, `uploadFile` | `({ url, headers, getHeaders })`, `(files, { url, fieldName, extraData, onProgress }) → Promise` | Multipart upload over XHR |
 | `attachProgressSource`, `progressSourceAttached`, `subscribeToProgress`, `describeProgress`, `describeComplete` | `(subscribe)`, `() → boolean`, `(key, handler) → unsubscribe`, `(data, noun?)`, `(data, noun?)` | The progress event source and its sentences |
 
@@ -165,7 +167,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`, `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
 
@@ -294,13 +296,16 @@ configureUpload({ url: '/uploads', getHeaders: () => ({ Authorization: 'Bearer '
 
 | prop | type | meaning |
 |---|---|---|
-| `onInspect` | `(filePath, file) => Promise<{ format, parts? }>` | **Required.** Say what an uploaded file contains. `parts` holds, for example, an Excel workbook's sheet names. |
-| `onCommit` | `(filePath, [{ part, target }], { originalName }) => Promise<{ results } \| results[]>` | **Required.** Load the included parts into their targets. |
+| `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. |
 | `accept` | `string` | The file input's `accept` attribute, for example `'.csv,.json,.xlsx,.xls'` |
 | `targetLabel` | `string` | Placeholder for the target name (default `'Target'`) |
+| `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).
+
 `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
@@ -310,9 +315,23 @@ 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?, 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.
 
+## Dropped rows
+
+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
 
 ```jsx
@@ -455,6 +474,7 @@ These create their own DOM nodes with inline styles, so they need no provider, m
 | `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
 

package/package.json

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

package/src/dataImport/dataImport.js

@@ -16,8 +16,26 @@ export function sanitizeTargetName(name) {
     .replace(/^_+|_+$/g, '') || 'table';
 }
 
-// inspectResult: { filePath, format, originalName?, parts?: string[] }
-// -> [{ part: string|null, target: string, include: boolean }]
+// What the inspect step found wrong with one part, if anything:
+//   inspectResult.checks = { [part]: [{ key, message, fixLabel?, fixDefault? }] }
+// (the key '' for a file that is one unit). A check with a fixLabel offers a
+// fix the person switches on or off before importing; its choice travels
+// with the mapping as fixes[key].
+export function checksFor(inspectResult, part) {
+  var all = (inspectResult && inspectResult.checks) || {};
+  return all[part == null ? '' : part] || [];
+}
+
+function initialFixes(inspectResult, part) {
+  var fixes = {};
+  checksFor(inspectResult, part).forEach(function(c) {
+    if (c.fixLabel) fixes[c.key] = c.fixDefault !== false;
+  });
+  return fixes;
+}
+
+// inspectResult: { filePath, format, originalName?, parts?: string[], checks? }
+// -> [{ part: string|null, target: string, include: boolean, 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
@@ -25,8 +43,8 @@ export function sanitizeTargetName(name) {
 export function buildInitialMappings(inspectResult) {
   if (inspectResult.parts && inspectResult.parts.length) {
     return inspectResult.parts.map(function(part) {
-      return { part: part, target: sanitizeTargetName(part), include: true };
+      return { part: part, target: sanitizeTargetName(part), include: true, fixes: initialFixes(inspectResult, part) };
     });
   }
-  return [{ part: null, target: sanitizeTargetName(inspectResult.originalName || 'data'), include: true }];
+  return [{ part: null, target: sanitizeTargetName(inspectResult.originalName || 'data'), include: true, fixes: initialFixes(inspectResult, null) }];
 }

package/src/dataImport/designs/DataImportSample.jsx

@@ -2,7 +2,8 @@ import './dataImport.css';
 
 export default function DataImportSample({
   file, inspecting, inspected, mappings, committing, results, error,
-  handleFileChange, updateMapping, handleCommit, reset, accept, targetLabel
+  handleFileChange, updateMapping, setFix, checksOf, handleCommit, reset, accept, targetLabel,
+  canViewDropped, viewDropped
 }) {
   return (
     <div className="xeplr-data-import">
@@ -37,6 +38,31 @@ export default function DataImportSample({
                   onChange={function(e) { updateMapping(i, { target: e.target.value }); }}
                   placeholder={targetLabel}
                 />
+                {/* 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) {
+                  return (
+                    <div key={c.key} className="xeplr-data-import-check" role="alert">
+                      <p className="xeplr-data-import-check-message">{c.message}</p>
+                      {c.fixLabel && (
+                        <label className="xeplr-data-import-check-fix">
+                          <input
+                            type="checkbox"
+                            checked={Boolean(m.fixes && m.fixes[c.key])}
+                            disabled={!m.include}
+                            onChange={function(e) { setFix(i, c.key, e.target.checked); }}
+                          />
+                          {c.fixLabel}
+                        </label>
+                      )}
+                      {(c.examples || []).length > 0 && (
+                        <ul className="xeplr-data-import-check-examples">
+                          {c.examples.map(function(x, xi) { return <li key={xi}>{x}</li>; })}
+                        </ul>
+                      )}
+                    </div>
+                  );
+                })}
               </div>
             );
           })}
@@ -61,6 +87,20 @@ export default function DataImportSample({
                 <span className={r.success ? 'xeplr-data-import-result-ok' : 'xeplr-data-import-result-fail'}>
                   {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

@@ -78,7 +78,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,6 +96,13 @@ 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',

package/src/dataImport/designs/dataImport.css

@@ -96,3 +96,69 @@
 .xeplr-import-history-status-failed { color: var(--xeplr-danger, #ff6b6b); }
 .xeplr-import-history-status-rolled-back { color: var(--xeplr-text-muted, #888); }
 .xeplr-import-history-error { color: var(--xeplr-text-secondary, #999); }
+
+/* What the inspect step found in a part — on its own line under the part,
+   with the fix (when one is offered) as a checkbox the person decides. */
+.xeplr-data-import-mapping-row { flex-wrap: wrap; }
+.xeplr-data-import-check {
+  flex-basis: 100%;
+  margin: 2px 0 4px;
+  padding: 10px 12px;
+  border-radius: 8px;
+  border: 1px solid var(--xeplr-warning, #a86a00);
+  background: var(--xeplr-warning-bg, rgba(168, 106, 0, 0.08));
+  color: var(--xeplr-text-primary, #e0e0e0);
+  font-size: 13px;
+}
+.xeplr-data-import-check-message { margin: 0 0 6px; line-height: 1.45; }
+.xeplr-data-import-check-fix { display: flex; align-items: center; gap: 8px; font-weight: 600; cursor: pointer; }
+.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; }

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';

package/src/dataImport/droppedRows.js

@@ -0,0 +1,86 @@
+// ROWS AN IMPORT DROPPED — the ones the database refused — as the dropped-rows
+// view shows them, copies them and counts them. Pure: no React, no fetch.
+//
+// The app's onLoadDropped(job) answers:
+//   { columns: ['sku', 'qty'],                       // the file's own, in order
+//     rows: [{ rowNum: 5, reason: '…', values: { sku: 'S5', qty: -1 } }],
+//     total: 2,                                      // rows kept to look at
+//     dropped: 2 }                                   // rows the import counted
+
+/** How many rows a job or an import result dropped (either shape). */
+export function droppedCount(job) {
+  if (!job) return 0;
+  var n = job.rowsDropped != null ? job.rowsDropped : job.dropped;
+  return Number(n) || 0;
+}
+
+/**
+ * The view's table: a row number, the reason, then the file's columns. Keys
+ * are positional (c0, c1, …) because a column name can hold a dot, which a
+ * table's accessor reads as a path.
+ *
+ * @returns {{ columns: [{ key, header }], rows: object[] }}
+ */
+export function droppedTable(data) {
+  var names = (data && data.columns) || [];
+  var columns = [{ key: 'rowNum', header: 'Row' }, { key: 'reason', header: 'Why it was dropped' }]
+    .concat(names.map(function(name, i) { return { key: 'c' + i, header: name }; }));
+  var rows = ((data && data.rows) || []).map(function(r) {
+    var row = { rowNum: r.rowNum == null ? '' : r.rowNum, reason: r.reason || '' };
+    names.forEach(function(name, i) { row['c' + i] = displayValue(r.values ? r.values[name] : null); });
+    return row;
+  });
+  return { columns: columns, rows: rows };
+}
+
+function displayValue(v) {
+  if (v == null) return '';
+  return typeof v === 'object' ? JSON.stringify(v) : String(v);
+}
+
+/**
+ * The rows as tab-separated text with a header — what Excel takes from the
+ * clipboard as cells. The file's columns only, like the download: pasted,
+ * fixed and saved, it imports again as it is. A value holding a tab, a line
+ * break or a quote is quoted, its quotes doubled, as Excel itself copies it.
+ */
+export function droppedAsTsv(data) {
+  var names = (data && data.columns) || [];
+  var lines = [names.map(tsvCell).join('\t')];
+  ((data && data.rows) || []).forEach(function(r) {
+    lines.push(names.map(function(name) { return tsvCell(displayValue(r.values ? r.values[name] : null)); }).join('\t'));
+  });
+  return lines.join('\r\n');
+}
+
+export function tsvCell(value) {
+  var s = value == null ? '' : String(value);
+  return /[\t\r\n"]/.test(s) ? '"' + s.replace(/"/g, '""') + '"' : s;
+}
+
+/**
+ * What to say above the rows: the heading, and a note when not every dropped
+ * row is here — the view shows the first ones, or the import predates rows
+ * being kept and has only a count.
+ */
+export function droppedSummary(job, data) {
+  var dropped = data && data.dropped != null ? Number(data.dropped) : droppedCount(job);
+  var total = data ? Number(data.total) || 0 : 0;
+  var shown = data && data.rows ? data.rows.length : 0;
+  var heading = plural(dropped, 'row') + ' dropped' +
+    (job && job.originalFileName ? ' from ' + job.originalFileName + (job.part ? ' (' + job.part + ')' : '') : '') +
+    (job && job.target ? ' → ' + job.target : '');
+  var note = null;
+  if (data && total === 0 && dropped > 0) {
+    note = 'These rows were not kept — this import ran before dropped rows were saved. Import the file again to see them.';
+  } else if (data && total < dropped) {
+    note = 'Only ' + plural(total, 'row') + ' of ' + dropped + ' were kept; the import stopped recording after too many failures in a row.';
+  } else if (data && shown < total) {
+    note = 'Showing the first ' + shown.toLocaleString() + ' of ' + total.toLocaleString() + '. Download has all of them.';
+  }
+  return { heading: heading, note: note };
+}
+
+function plural(n, word) {
+  return Number(n).toLocaleString() + ' ' + word + (Number(n) === 1 ? '' : 's');
+}

package/src/dataImport/pages.jsx

@@ -1,17 +1,40 @@
 import { useDataImportController } from './useDataImportController.js';
 import { useImportHistoryController } from './useImportHistoryController.js';
+import { useDroppedRowsController } from './useDroppedRowsController.js';
 import DataImportSample from './designs/DataImportSample.jsx';
 import ImportHistorySample from './designs/ImportHistorySample.jsx';
-import { useDesignValidator, DATA_IMPORT_RULES, IMPORT_HISTORY_RULES } from './validateDesign.js';
+import DroppedRowsSample from './designs/DroppedRowsSample.jsx';
+import { useDesignValidator, DATA_IMPORT_RULES, IMPORT_HISTORY_RULES, DROPPED_ROWS_RULES } from './validateDesign.js';
 
+// Props: onInspect, onCommit, … and, to show the rows an import dropped,
+// onLoadDropped(job) and onDownloadDropped(job) (see useDroppedRowsController).
 export function DataImportPage(props) {
   var controller = useDataImportController(props);
+  var dropped = useDroppedRowsController(props);
   var ref = useDesignValidator('DataImportPage', DATA_IMPORT_RULES);
-  return <div ref={ref}><DataImportSample {...controller} /></div>;
+  return (
+    <div ref={ref}>
+      <DataImportSample {...controller} canViewDropped={dropped.canView} viewDropped={dropped.open} />
+      {dropped.job && <DroppedRowsPage {...dropped} />}
+    </div>
+  );
 }
 
 export function ImportHistoryPage(props) {
   var controller = useImportHistoryController(props);
+  var dropped = useDroppedRowsController(props);
   var ref = useDesignValidator('ImportHistoryPage', IMPORT_HISTORY_RULES);
-  return <div ref={ref}><ImportHistorySample {...controller} /></div>;
+  return (
+    <div ref={ref}>
+      <ImportHistorySample {...controller} canViewDropped={dropped.canView} viewDropped={dropped.open} />
+      {dropped.job && <DroppedRowsPage {...dropped} />}
+    </div>
+  );
+}
+
+// The dropped-rows dialog, validated as it opens — its required buttons only
+// exist while it is on screen.
+export function DroppedRowsPage(props) {
+  var ref = useDesignValidator('DroppedRows', DROPPED_ROWS_RULES);
+  return <div ref={ref}><DroppedRowsSample {...props} /></div>;
 }

package/src/dataImport/useDataImportController.js

@@ -1,16 +1,18 @@
 import { useState } from 'react';
 import { uploadFile } from '../fileUpload/uploadFile.js';
-import { buildInitialMappings } from './dataImport.js';
+import { buildInitialMappings, checksFor } from './dataImport.js';
 
 /**
  * @param {object} options
  * @param {string} [options.accept] - file input accept attribute, e.g. '.csv,.json,.xlsx,.xls'
  * @param {string} [options.targetLabel='Target'] - placeholder/label for the target-name field
- * @param {(filePath: string, file: File) => Promise<{format: string, parts?: string[]}>} options.onInspect
+ * @param {(filePath: string, file: File) => Promise<{format: string, parts?: string[], checks?: object}>} options.onInspect
  *   - 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}[], meta: {originalName: string}) => Promise<{results: object[]}>} options.onCommit
+ * @param {(filePath: string, mappings: {part: string|null, target: 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.
  *     meta.originalName is the picked file's own name (not the server-side
  *     path) — pass it through if the app wants it recorded (e.g. import
@@ -61,6 +63,15 @@ export function useDataImportController(options = {}) {
     }
   }
 
+  // A fix the inspect step offered, switched on or off for one part.
+  function setFix(index, key, on) {
+    setMappings(function(prev) {
+      var next = prev.slice();
+      next[index] = Object.assign({}, next[index], { fixes: Object.assign({}, next[index].fixes, { [key]: on }) });
+      return next;
+    });
+  }
+
   function updateMapping(index, patch) {
     setMappings(function(prev) {
       var next = prev.slice();
@@ -75,7 +86,7 @@ export function useDataImportController(options = {}) {
     setCommitting(true);
     setError('');
     try {
-      var payload = included.map(function(m) { return { part: m.part, target: m.target }; });
+      var payload = included.map(function(m) { return { part: m.part, target: m.target, fixes: m.fixes || {} }; });
       var res = await options.onCommit(inspected.filePath, payload, { originalName: inspected.originalName });
       setResults((res && res.results) || res || []);
     } catch (err) {
@@ -87,7 +98,8 @@ export function useDataImportController(options = {}) {
 
   return {
     file, inspecting, inspected, mappings, committing, results, error,
-    handleFileChange, updateMapping, handleCommit, reset,
+    handleFileChange, updateMapping, setFix, handleCommit, reset,
+    checksOf: function(part) { return checksFor(inspected, part); },
     accept: options.accept,
     targetLabel: options.targetLabel || 'Target'
   };

package/src/dataImport/useDroppedRowsController.js

@@ -0,0 +1,95 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { droppedAsTsv, droppedCount, droppedSummary, droppedTable } from './droppedRows.js';
+
+/**
+ * The rows an import dropped: open them, copy them, download them.
+ *
+ * @param {object} options
+ * @param {(job) => Promise<{columns, rows, total, dropped}>} [options.onLoadDropped]
+ *        the app's read of a job's dropped rows. Without it nothing offers to show them.
+ * @param {(job) => Promise<any>} [options.onDownloadDropped]
+ *        the app saves them as a file (an .xlsx that imports again as it is)
+ *
+ * job: { id, rowsDropped|dropped, originalFileName?, part?, target? } — an
+ * import-history row, or an import result with its jobId as id.
+ */
+export function useDroppedRowsController(options = {}) {
+  var [job, setJob] = useState(null);
+  var [data, setData] = useState(null);
+  var [loading, setLoading] = useState(false);
+  var [error, setError] = useState('');
+  var [copied, setCopied] = useState(false);
+  var [downloading, setDownloading] = useState(false);
+  var copiedTimer = useRef(null);
+  var onLoad = options.onLoadDropped;
+
+  useEffect(function() { return function() { clearTimeout(copiedTimer.current); }; }, []);
+
+  var canView = useCallback(function(j) {
+    return !!onLoad && !!j && j.id != null && droppedCount(j) > 0;
+  }, [onLoad]);
+
+  var open = useCallback(async function(j) {
+    setJob(j);
+    setData(null);
+    setError('');
+    setCopied(false);
+    setLoading(true);
+    try {
+      setData(await onLoad(j));
+    } catch (err) {
+      setError(err.message || 'Could not load the dropped rows');
+    } finally {
+      setLoading(false);
+    }
+  }, [onLoad]);
+
+  function close() {
+    setJob(null);
+    setData(null);
+    setError('');
+  }
+
+  async function copy() {
+    if (!data) return;
+    try {
+      await navigator.clipboard.writeText(droppedAsTsv(data));
+      setCopied(true);
+      clearTimeout(copiedTimer.current);
+      copiedTimer.current = setTimeout(function() { setCopied(false); }, 2000);
+    } catch (err) {
+      setError('Could not copy — the browser refused the clipboard. Use Download instead.');
+    }
+  }
+
+  async function download() {
+    if (!options.onDownloadDropped || !job) return;
+    setDownloading(true);
+    setError('');
+    try {
+      await options.onDownloadDropped(job);
+    } catch (err) {
+      setError(err.message || 'Download failed');
+    } finally {
+      setDownloading(false);
+    }
+  }
+
+  return {
+    job: job,
+    data: data,
+    table: data ? droppedTable(data) : null,
+    summary: job ? droppedSummary(job, data) : null,
+    loading: loading,
+    error: error,
+    copied: copied,
+    downloading: downloading,
+    canDownload: !!options.onDownloadDropped && !!data && data.total > 0,
+    canCopy: !!data && data.rows && data.rows.length > 0,
+    canView: canView,
+    open: open,
+    close: close,
+    copy: copy,
+    download: download
+  };
+}

package/src/dataImport/validateDesign.js

@@ -66,3 +66,10 @@ export var DATA_IMPORT_RULES = [
 ];
 
 export var IMPORT_HISTORY_RULES = [];
+
+// Checked when the dialog opens — it is not on the page before.
+export var DROPPED_ROWS_RULES = [
+  { id: 'xeplr-dropped-rows-copy', label: 'Copy button' },
+  { id: 'xeplr-dropped-rows-download', label: 'Download button' },
+  { id: 'xeplr-dropped-rows-close', label: 'Close button' }
+];

package/src/index.js

@@ -40,6 +40,16 @@ export { IMPORT_HISTORY_RULES } from './dataImport/validateDesign.js';
 export { ImportHistorySample } from './dataImport/designs/index.js';
 export { ImportHistoryPage } from './dataImport/pages.jsx';
 
+// DroppedRows — the rows an import's database refused, with each one's place
+// in the file and the reason; Copy (tab-separated, pastes into Excel) and
+// Download (app-supplied onDownloadDropped). Built into DataImportPage and
+// ImportHistoryPage when the app passes onLoadDropped.
+export { droppedCount, droppedTable, droppedAsTsv, droppedSummary, tsvCell } from './dataImport/droppedRows.js';
+export { useDroppedRowsController } from './dataImport/useDroppedRowsController.js';
+export { DROPPED_ROWS_RULES } from './dataImport/validateDesign.js';
+export { DroppedRowsSample } from './dataImport/designs/index.js';
+export { DroppedRowsPage } from './dataImport/pages.jsx';
+
 // NumberField — model
 export {
   NUMBER_TYPES,